Models

API reference for all pydantic models used.

vizro.models

Accordion

Accordion(**data)

Bases: VizroBaseModel

Accordion to be used as nav_selector in Navigation.

Parameters:

• type (Literal['accordion']) –

  Defaults to "accordion".

• pages (Dict[str, List[str]]) –

  Mapping from name of a pages group to a list of page IDs. Defaults to {}.

Action

Action(**data)

Bases: VizroBaseModel

Action to be inserted into actions of relevant component.

Parameters:

• function (CapturedCallable) –

  See CapturedCallable.

• inputs (List[str]) –

  Inputs in the form <component_id>.<property> passed to the action function. Defaults to [].

• outputs (List[str]) –

  Outputs in the form <component_id>.<property> changed by the action function. Defaults to [].

build

build()

Builds a callback for the Action model and returns required components for the callback.

Returns List of required components (e.g. dcc.Download) for the Action model added to the Dashboard container.

AgGrid

AgGrid(**data)

Bases: VizroBaseModel

Wrapper for dash-ag-grid.AgGrid to visualize grids in dashboard.

Parameters:

• type (Literal['ag_grid']) –

  Defaults to "ag_grid".

• figure (CapturedCallable) –

  AgGrid like object to be displayed. For more information see: dash-ag-grid.AgGrid.

• title (str) –

  Title of the table. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Button

Button(**data)

Bases: VizroBaseModel

Component provided to Page to trigger any defined action in Page.

Parameters:

• type (Literal['button']) –

  Defaults to "button".

• text (str) –

  Text to be displayed on button. Defaults to "Click me!".

• actions (List[Action]) –

  See Action. Defaults to [].

Card

Card(**data)

Bases: VizroBaseModel

Creates a card utilizing dcc.Markdown as title and text component.

Parameters:

• type (Literal['card']) –

  Defaults to "card".

• text (str) –

  Markdown string to create card title/text that should adhere to the CommonMark Spec.

• href (str) –

  URL (relative or absolute) to navigate to. If not provided the Card serves as a text card only. Defaults to "".

Checklist

Checklist(**data)

Bases: VizroBaseModel

Categorical multi-option selector Checklist.

Can be provided to Filter or Parameter. Based on the underlying dcc.Checklist.

Parameters:

• type (Literal['checklist']) –

  Defaults to "checklist".

• options (OptionsType) –

  See OptionsType. Defaults to [].

• value (Optional[MultiValueType]) –

  See MultiValueType. Defaults to None.

• title (str) –

  Title to be displayed. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Container

Container(**data)

Bases: VizroBaseModel

Container to group together a set of components on a page.

Parameters:

• type (Literal['container']) –

  Defaults to "container".

• components (List[ComponentType]) –

  See ComponentType. At least one component has to be provided.

• title (str) –

  Title to be displayed.

• layout (Layout) –

  Layout to place components in. Defaults to None.

Dashboard

Dashboard(**data)

Bases: VizroBaseModel

Vizro Dashboard to be used within Vizro.

Parameters:

• pages (List[Page]) –

  See Page.

• theme (Literal['vizro_dark', 'vizro_light']) –

  Layout theme to be applied across dashboard. Defaults to vizro_dark.

• navigation (Navigation) –

  See Navigation. Defaults to None.

• title (str) –

  Dashboard title to appear on every page on top left-side. Defaults to "".

DatePicker

DatePicker(**data)

Bases: VizroBaseModel

Temporal single/range option selector DatePicker.

Can be provided to Filter or Parameter. Based on the underlying dmc.DatePicker or dmc.DateRangePicker.

Parameters:

• type (Literal['date_picker']) –

  Defaults to "date_picker".

• min (Optional[date]) –

  Start date for date picker. Defaults to None.

• max (Optional[date]) –

  End date for date picker. Defaults to None.

• value (Union[List[date], date]) –

  Default date/dates for date picker. Defaults to None.

• title (str) –

  Title to be displayed. Defaults to "".

• range (bool) –

  Boolean flag for displaying range picker. Default to True.

• actions (List[Action]) –

  See Action. Defaults to [].

Dropdown

Dropdown(**data)

Bases: VizroBaseModel

Categorical single/multi-option selector Dropdown.

Can be provided to Filter or Parameter. Based on the underlying dcc.Dropdown.

Parameters:

• type (Literal['dropdown']) –

  Defaults to "dropdown".

• options (OptionsType) –

  See OptionsType. Defaults to [].

• value (Optional[Union[SingleValueType, MultiValueType]]) –

  See SingleValueType and MultiValueType. Defaults to None.

• multi (bool) –

  Whether to allow selection of multiple values. Defaults to True.

• title (str) –

  Title to be displayed. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Filter

Filter(**data)

Bases: VizroBaseModel

Filter the data supplied to targets on the Page.

Examples:

>>> print(repr(Filter(column="species")))

Parameters:

• type (Literal['filter']) –

  Defaults to "filter".

• column (str) –

  Column of DataFrame to filter.

• targets (List[ModelID]) –

  Target component to be affected by filter. If none are given then target all components on the page that use column.

• selector (SelectorType) –

  See SelectorType. Defaults to None.

Graph

Graph(**data)

Bases: VizroBaseModel

Wrapper for dcc.Graph to visualize charts in dashboard.

Parameters:

• type (Literal['graph']) –

  Defaults to "graph".

• figure (CapturedCallable) –

  See CapturedCallable.

• actions (List[Action]) –

  See Action. Defaults to [].

Layout

Layout(**data)

Bases: VizroBaseModel

Grid specification to place chart/components on the Page.

Parameters:

• grid (List[List[int]]) –

  Grid specification to arrange components on screen.

• row_gap (str) –

  Gap between rows in px. Defaults to "12px".

• col_gap (str) –

  Gap between columns in px. Defaults to "12px".

• row_min_height (str) –

  Minimum row height in px. Defaults to "0px".

• col_min_width (str) –

  Minimum column width in px. Defaults to "0px".

build

build()

Creates empty container with inline style to later position components in.

NavBar

NavBar(**data)

Bases: VizroBaseModel

Navigation bar to be used as a nav_selector for Navigation.

Parameters:

• type (Literal['nav_bar']) –

  Defaults to "nav_bar".

• pages (Dict[str, List[str]]) –

  Mapping from name of a pages group to a list of page IDs. Defaults to {}.

• items (List[NavLink]) –

  See NavLink. Defaults to [].

NavLink

NavLink(**data)

Bases: VizroBaseModel

Icon that serves as a navigation link to be used in navigation bar of Dashboard.

Parameters:

• pages (NavPagesType) –

  See NavPagesType. Defaults to [].

• label (str) –

  Text description of the icon for use in tooltip.

• icon (str) –

  Icon name from Google Material icons library. Defaults to "".

Navigation

Navigation(**data)

Bases: VizroBaseModel

Navigation in Dashboard to structure Pages.

Parameters:

• pages (NavPagesType) –

  See NavPagesType. Defaults to [].

• nav_selector (NavSelectorType) –

  See NavSelectorType. Defaults to None.

Page

Page(**data)

Bases: VizroBaseModel

A page in Dashboard with its own URL path and place in the Navigation.

Parameters:

• components (List[ComponentType]) –

  See ComponentType. At least one component has to be provided.

• title (str) –

  Title to be displayed.

• description (str) –

  Description for meta tags.

• layout (Layout) –

  Layout to place components in. Defaults to None.

• controls (List[ControlType]) –

  See ControlType. Defaults to [].

• path (str) –

  Path to navigate to page. Defaults to "".

Parameter

Parameter(**data)

Bases: VizroBaseModel

Alter the arguments supplied to any targets on the Page.

Examples:

>>> print(repr(Parameter(
>>>    targets=["scatter.x"], selector=Slider(min=0, max=1, default=0.8, title="Bubble opacity"))))

Parameters:

• type (Literal['parameter']) –

  Defaults to "parameter".

• targets (List[str]) –

  Targets in the form of <target_component>.<target_argument>.

• selector (SelectorType) –

  See SelectorType. Converts selector value "NONE" into None to allow optional parameters.

RadioItems

RadioItems(**data)

Bases: VizroBaseModel

Categorical single-option selector RadioItems.

Can be provided to Filter or Parameter. Based on the underlying dcc.RadioItems.

Parameters:

• type (Literal['radio_items']) –

  Defaults to "radio_items".

• options (OptionsType) –

  See OptionsType. Defaults to [].

• value (Optional[SingleValueType]) –

  See SingleValueType. Defaults to None.

• title (str) –

  Title to be displayed. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

RangeSlider

RangeSlider(**data)

Bases: VizroBaseModel

Numeric multi-option selector RangeSlider.

Can be provided to Filter or Parameter. Based on the underlying dcc.RangeSlider.

Parameters:

• type (Literal['range_slider']) –

  Defaults to "range_slider".

• min (Optional[float]) –

  Start value for slider. Defaults to None.

• max (Optional[float]) –

  End value for slider. Defaults to None.

• step (Optional[float]) –

  Step-size for marks on slider. Defaults to None.

• marks (Optional[Dict[int, Union[str, dict]]]) –

  Marks to be displayed on slider. Defaults to {}.

• value (Optional[List[float]]) –

  Default start and end value for slider. Must be 2 items. Defaults to None.

• title (str) –

  Title to be displayed. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Slider

Slider(**data)

Bases: VizroBaseModel

Numeric single-option selector Slider.

Can be provided to Filter or Parameter. Based on the underlying dcc.Slider.

Parameters:

• type (Literal['range_slider']) –

  Defaults to "range_slider".

• min (Optional[float]) –

  Start value for slider. Defaults to None.

• max (Optional[float]) –

  End value for slider. Defaults to None.

• step (Optional[float]) –

  Step-size for marks on slider. Defaults to None.

• marks (Optional[Dict[int, Union[str, dict]]]) –

  Marks to be displayed on slider. Defaults to {}.

• value (Optional[float]) –

  Default value for slider. Defaults to None.

• title (str) –

  Title to be displayed. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Table

Table(**data)

Bases: VizroBaseModel

Wrapper for dash_table.DataTable to visualize tables in dashboard.

Parameters:

• type (Literal['table']) –

  Defaults to "table".

• figure (CapturedCallable) –

  Table like object to be displayed. For more information see: dash_table.DataTable.

• title (str) –

  Title of the table. Defaults to "".

• actions (List[Action]) –

  See Action. Defaults to [].

Tabs

Tabs(**data)

Bases: VizroBaseModel

Tabs to group together a set of containers on a page.

Parameters:

• type (Literal['tabs']) –

  Defaults to "tabs".

• tabs (List[Container]) –

  See Container.

VizroBaseModel

VizroBaseModel(**data)

Bases: BaseModel

All models that are registered to the model manager should inherit from this class.

Parameters:

• id (str) –

  ID to identify model. Must be unique throughout the whole dashboard. Defaults to "". When no ID is chosen, ID will be automatically generated.

add_type classmethod

add_type(field_name, new_type)

Adds a new type to an existing field based on a discriminated union.

Parameters:

• field_name (str) –

  Field that new type will be added to

• new_type (Type[Any]) –

  New type to add to discriminated union

vizro.models.types

Types used in pydantic fields.

ComponentType module-attribute

ComponentType = Annotated[Union['AgGrid', 'Button', 'Card', 'Container', 'Graph', 'Table', 'Tabs'], Field(discriminator='type', description='Component that makes up part of the layout on the page.')]

Discriminated union. Type of component that makes up part of the layout on the page: Button, Card, Table, Graph or AgGrid.

ControlType module-attribute

ControlType = Annotated[Union['Filter', 'Parameter'], Field(discriminator='type', description='Control that affects components on the page.')]

Discriminated union. Type of control that affects components on the page: Filter or Parameter.

MultiValueType module-attribute

MultiValueType = Union[List[StrictBool], List[float], List[str], List[date]]

Permissible value types for multi-value selectors. Values are displayed as default.

NavPagesType module-attribute

NavPagesType = Union[List[str], Dict[str, List[str]]]

List of page IDs or a mapping from name of a group to a list of page IDs (for hierarchical sub-navigation).

NavSelectorType module-attribute

NavSelectorType = Annotated[Union['Accordion', 'NavBar'], Field(discriminator='type', description='Component for rendering navigation.')]

Discriminated union. Type of component for rendering navigation: Accordion or NavBar.

OptionsType module-attribute

OptionsType = Union[List[StrictBool], List[float], List[str], List[date], List[OptionsDictType]]

Permissible options types for selectors. Options are available choices for user to select from.

SelectorType module-attribute

SelectorType = Annotated[Union['Checklist', 'DatePicker', 'Dropdown', 'RadioItems', 'RangeSlider', 'Slider'], Field(discriminator='type', description='Selectors to be used inside a control.')]

Discriminated union. Type of selector to be used inside a control: Checklist, DatePicker, Dropdown, RadioItems, RangeSlider or Slider.

SingleValueType module-attribute

SingleValueType = Union[StrictBool, float, str, date]

Permissible value types for single-value selectors. Values are displayed as default.

CapturedCallable

Stores a captured function call to use in a dashboard.

Users do not need to instantiate this class directly. Instances are instead generated automatically through the capture decorator. Some of the functionality is similar to functools.partial.

Ready-to-use CapturedCallable instances are provided by Vizro. In this case refer to the user guide on Charts/Graph, Table or Actions to see available choices.

(Advanced) In case you would like to create your own CapturedCallable, please refer to the user guide on custom charts, custom tables or custom actions.

OptionsDictType

Bases: TypedDict

Permissible sub-type for OptionsType. Needs to be in the format of {"label": XXX, "value": XXX}.

capture

Captures a function call to create a CapturedCallable.

This is used to add the functionality required to make graphs and actions work in a dashboard. Typically, it should be used as a function decorator. There are four possible modes: "graph", "table", "ag_grid" and "action".

Examples >>> @capture("graph") >>> def graph_function(): >>> ... >>> @capture("table") >>> def table_function(): >>> ... >>> @capture("ag_grid") >>> def ag_grid_function(): >>> ... >>> @capture("action") >>> def action_function(): >>> ...

For further help on the use of @capture("graph"), you can refer to the guide on custom graphs. For further help on the use of @capture("table") or @capture("ag_grid"), you can refer to the guide on custom tables. For further help on the use of @capture("action"), you can refer to the guide on custom actions.