Skip to content

How to use layouts

This guide shows you how to use the Layout to arrange charts/components on the screen and customize the grid specifications.

The Page model accepts the layout argument, where you can input your Layout with a custom grid.

Using the default layout

The layout argument of the Page model is optional. If no layout is specified, all charts/components will automatically be vertically stacked down the page in one column. If that is your desired layout, you can create your charts/components without providing a Layout.

Default Layout

from vizro import Vizro
import vizro.models as vm

page = vm.Page(
    title="two_left",
    components=[vm.Card(text="""# Component 0"""),
                vm.Card(text="""# Component 1""")]

)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
- components:
    - text: |
        # Component 0
      type: card
    - text: |
        # Component 1
      type: card
  title: two_left

Layout

Configuring the grid

To customize the grid arrangement, you can configure the grid parameter of the Layout model. The example below shows how the grid works and how to specify a valid one:

Basic Example
grid = [[0, 1],
        [0, 2]]
  • The grid needs to be provided as List[List[int]] (e.g. grid = [[0, 1], [0, 2]])
  • The integers in the grid correspond to the index of the chart/component inside the list of components provided to Page
  • The number of integers in the grid needs to match the number of chart/components provided
  • Each sub-list corresponds to a grid row (e.g. row 1 = [0, 1] and row 2 = [0, 2])
  • Each element inside the sub-list corresponds to a grid column (e.g. column 1 = [0, 0] and column 2 = [1, 2])
  • The integers in the grid need to be consecutive integers starting with 0 (e.g. 0, 1, 2)
  • Each chart/component will take the entire space of its grid area (empty spaces are currently not enabled)
  • The area spanned by a chart/component in the grid must be rectangular
  • The grid can be arbitrarily large, allowing arbitrarily granular control of the grid:
Advanced Example
grid=[[0, 1, 3, 4],
      [2, 2, 3, 4]]

Stacking components

  • When no Layout is specified, components will automatically be stacked vertically down the page in one column. For instance, if you have three components, the default Layout.grid will be grid = [[0], [1], [2]]. This means three equally sized rows, each containing a component spanning the entire width.
  • To stack components horizontally, set the grid as grid = [[0, 1, 2]]. This defines a single row that occupies the entire width and height, divided into three equal columns.

Stacking components

Grid - Basic Example

Grid Arrangement - Basic Example

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
    title="one_left_two_right",
    layout=vm.Layout(grid=[[0, 1],
                           [0, 2]]),
    components=[vm.Card(text="""# Component 0"""),
                vm.Card(text="""# Component 1"""),
                vm.Card(text="""# Component 2"""),
                ],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
- components:
    - text: |
        # Component 0
      type: card
    - text: |
        # Component 1
      type: card
    - text: |
        # Component 2
      type: card
  layout:
    grid: [[0, 1], [0, 2]]
  title: one_left_two_right

Grid

Grid - Advanced Example

Generally, the Layout provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.

If you want to divide the grid into subgrids with finer control over these, you can use Containers. See our section on when to use Containers vs. Page.layout for more information.

Grid Arrangement - Advanced Example

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro

gapminder = px.data.gapminder()

page = vm.Page(
    title="Custom Layout - Advanced Example",
    layout=vm.Layout(grid=[[0, 1, 3, 4],
                            [2, 2, 3, 4]]),
    components=[
        vm.Graph(
            figure=px.line(
                gapminder,
                title="Graph 1",
                x="year",
                y="lifeExp",
                color="continent",
            ),
        ),
        vm.Graph(
            figure=px.scatter(
                gapminder,
                title="Graph 2",
                x="gdpPercap",
                y="lifeExp",
                size="pop",
                color="continent",
            ),
        ),
        vm.Graph(
            figure=px.box(
                gapminder,
                title="Graph 3",
                x="continent",
                y="lifeExp",
                color="continent",
            ),
        ),
        vm.Graph(
            figure=px.line(
                gapminder,
                title="Graph 4",
                x="year",
                y="lifeExp",
                color="continent",
            ),
        ),
        vm.Graph(
            figure=px.scatter(
                gapminder,
                title="Graph 5",
                x="gdpPercap",
                y="lifeExp",
                size="pop",
                color="continent",
            ),
        ),
    ],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
  - components:
      - figure:
          _target_: line
          data_frame: gapminder
          x: year
          y: lifeExp
          color: continent
          title: Graph 1
        type: graph
      - figure:
          _target_: scatter
          data_frame: gapminder
          x: gdpPercap
          y: lifeExp
          size: pop
          color: continent
          title: Graph 2
        type: graph
      - figure:
          _target_: box
          data_frame: gapminder
          x: continent
          y: lifeExp
          color: continent
          title: Graph 3
        type: graph
      - figure:
          _target_: line
          data_frame: gapminder
          x: year
          y: lifeExp
          color: continent
          title: Graph 4
        type: graph
      - figure:
          _target_: scatter
          data_frame: gapminder
          x: gdpPercap
          y: lifeExp
          size: pop
          color: continent
          title: Graph 5
        type: graph
    layout:
      grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
    title: Custom Layout - Advanced Example

GridAdv

Using custom layout examples

Below is a table of examples you can take as a reference to create some selected layouts:

Configuration Description Image
layout=Layout(grid=[[0]]) or
layout=None
one_left
layout=Layout(grid=[[0],[1]]) or
layout=None
two_left
layout=Layout(grid=[[0,1]]) two_top
layout=Layout(grid=[[0],[1],[2]]) or
layout=None
three_left
layout=Layout(grid=[[0,1],[0,2]]) one_left_two_right
layout=Layout(grid=[[0,0],[1,2]]) one_top_two_bottom
layout=Layout(grid=[[0,1],[2,2]]) two_top_one_bottom
layout=Layout(grid=[[0,1],[0,2],[0,3]]) one_left_three_right
layout=Layout(grid=[[0,1],[2,3]]) two_left_two_right
layout=Layout(grid=[[0,3],[1,3],[2,3]]) three_left_one_right
layout=Layout(grid=[[0,0,0],[1,2,3]]) one_top_three_bottom
layout=Layout(grid=[[0,1,2],[3,3,3]]) three_top_one_bottom

Adding empty spaces to the grid

One approach to organize the dashboard's layout involves integrating empty spaces. This can be achieved by specifying -1 within your grid layout.

Example
grid = [[0, 1, -1],
        [0, 2, -1]]

Adding Empty Spaces

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
    title="Adding empty spaces",
    layout=vm.Layout(grid=[[0, 1, -1],
                           [0, 2, -1]]),
    components=[vm.Card(text="""# Component 0"""),
                vm.Card(text="""# Component 1"""),
                vm.Card(text="""# Component 2"""),
                ],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
- components:
    - text: |
        # Component 0
      type: card
    - text: |
        # Component 1
      type: card
    - text: |
        # Component 2
      type: card
  layout:
    grid: [[0, 1, -1], [0, 2, -1]]
  title: Adding empty spaces

GridEmpty

Controlling the scroll behavior

By default, the grid will try to fit all charts/components on the screen. This can lead to distortions of the chart/component looking squeezed in. You can control the scroll behavior of the grid by specifying the following:

  • row_min_height: Sets a chart/component's minimum height. Defaults to 0px.
  • col_min_width: Sets a chart/component's minimum width. Defaults to 0px.

Activate Scrolling

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
    title="Activate scrolling",
    layout=vm.Layout(grid=[[i] for i in range(8)],
                     row_min_height="240px"),
    components=[vm.Card(text="""# Component 0"""),
                vm.Card(text="""# Component 1"""),
                vm.Card(text="""# Component 2"""),
                vm.Card(text="""# Component 3"""),
                vm.Card(text="""# Component 4"""),
                vm.Card(text="""# Component 5"""),
                vm.Card(text="""# Component 6"""),
                vm.Card(text="""# Component 7"""),
                ],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
- components:
    - text: |
        # Component 0
      type: card
    - text: |
        # Component 1
      type: card
    - text: |
        # Component 2
      type: card
    - text: |
        # Component 2
      type: card
    - text: |
        # Component 4
      type: card
    - text: |
        # Component 5
      type: card
    - text: |
        # Component 6
      type: card
    - text: |
        # Component 7
      type: card
  layout:
    grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
    row_min_height: 240px
  title: Activate scrolling

GridScroll

Further customizations

For further customizations, such as changing the gap between row and column, please refer to the documentation of the Layout model.

Alternative layout approaches

In general, any arbitrarily granular layout can already be achieved using Page.layout alone and is our recommended approach if you just want to arrange components on a page with consistent row and/or column spacing.

Alternative layout approaches: Tabs and Containers

Tabs and Containers provide an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our user guide on Containers.

If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our user guide on Tabs.

tabs