Models

API reference for all pydantic models used.

vizro.models

Accordion

Bases: VizroBaseModel

Accordion to be used as nav_selector in Navigation.

Parameters:

• type (Literal['accordion']) –

  Defaults to "accordion".

• pages (dict[str, list[ModelID]]) –

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

Action

Bases: _BaseAction

Action to be inserted into actions of relevant component.

Parameters:

• function (CapturedCallable) –

  Action function.

• 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 [].

AgGrid

Bases: VizroBaseModel

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

Parameters:

• type (Literal['ag_grid']) –

  Defaults to "ag_grid".

• figure (CapturedCallable) –

  Function that returns a Dash AgGrid. See vizro.tables.

• title (str) –

  Title of the AgGrid. Defaults to "".

• header (str) –

  Markdown text positioned below the AgGrid.title. Follows the CommonMark specification. Ideal for adding supplementary information such as subtitles, descriptions, or additional context. Defaults to "".

• footer (str) –

  Markdown text positioned below the AgGrid. Follows the CommonMark specification. Ideal for providing further details such as sources, disclaimers, or additional notes. Defaults to "".

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

Button

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!".

• href (str) –

  URL (relative or absolute) to navigate to. Defaults to "".

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• variant (Literal['plain', 'filled', 'outlined']) –

  Predefined styles to choose from. Options are plain, filled or outlined. Defaults to filled.

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.Button and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Card

Bases: VizroBaseModel

Creates a card based on Markdown syntax.

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 "".

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.Card and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Checklist

Bases: VizroBaseModel

Categorical multi-option selector Checklist.

Can be provided to Filter or Parameter.

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 "".

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.Checklist and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Container

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 of the Container. Defaults to "".

• layout (Optional[LayoutType]) –

  Layout to place components in. Defaults to None.

• collapsed (Optional[bool]) –

  Boolean flag that determines whether the container is collapsed on initial load. Set to True for a collapsed state, False for an expanded state. Defaults to None, meaning the container is not collapsible.

• variant (Optional[Literal['plain', 'filled', 'outlined']]) –

  Predefined styles to choose from. Options are plain, filled or outlined. Defaults to plain (or outlined for collapsible container).

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.Container and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Dashboard

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

Bases: VizroBaseModel

Temporal single/range option selector DatePicker.

Can be provided to Filter or Parameter.

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 (Optional[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. Defaults to True.

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dmc.DatePickerInput and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dmc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Dropdown

Bases: VizroBaseModel

Categorical single/multi-option selector Dropdown.

Can be provided to Filter or Parameter.

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 "".

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dcc.Dropdown and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dcc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Figure

Bases: VizroBaseModel

Creates a figure-like object that can be displayed in the dashboard and is reactive to controls.

Parameters:

• type (Literal['figure']) –

  Defaults to "figure".

• figure (CapturedCallable) –

  Function that returns a figure-like object. See vizro.figures.

Filter

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. Defaults to [].

• selector (Optional[SelectorType]) –

  See SelectorType. Defaults to None.

Flex

Bases: VizroBaseModel

Flex Container to place chart/components on the Page.

Parameters:

• type (Literal['flex']) –

  Defaults to "flex".

• direction (Literal['row', 'column']) –

  Sets the direction of the flex items inside the container. Options are row or column. Defaults to column.

• gap (str) –

  Specifies the gap between rows and columns. Allowed units: 'px', 'rem', 'em', or '%'. Defaults to 24px.

• wrap (bool) –

  Determines whether flex items are forced onto a single line or can wrap onto multiple lines. If False, all items will be on one line. If True, items will wrap onto multiple lines. Defaults to False.

Graph

Bases: VizroBaseModel

Wrapper for dcc.Graph to visualize charts in dashboard.

Parameters:

• type (Literal['graph']) –

  Defaults to "graph".

• figure (CapturedCallable) –

  Function that returns a graph. See CapturedCallable][vizro.models.types.CapturedCallable].

• title (str) –

  Title of the Graph. Defaults to "".

• header (str) –

  Markdown text positioned below the Graph.title. Follows the CommonMark specification. Ideal for adding supplementary information such as subtitles, descriptions, or additional context. Defaults to "".

• footer (str) –

  Markdown text positioned below the Graph. Follows the CommonMark specification. Ideal for providing further details such as sources, disclaimers, or additional notes. Defaults to "".

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

Grid

Bases: VizroBaseModel

Grid specification to place chart/components on the Page.

Parameters:

• type (Literal['grid']) –

  Defaults to "grid".

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

  Grid specification to arrange components on screen.

• row_gap (str) –

  Specifies the gap between rows. Allowed units: 'px', 'rem', 'em', or '%'. Defaults to 24px.

• col_gap (str) –

  Specifies the gap between columns. Allowed units: 'px', 'rem', 'em', or '%'. Defaults to 24px.

• row_min_height (str) –

  Minimum row height in px. Allowed units: 'px', 'rem', 'em', or '%'. Defaults to 0px.

• col_min_width (str) –

  Minimum column width in px. Allowed unit are: 'px', 'rem', 'em', or '%'. Defaults to 0px.

Layout

Bases: Grid

Deprecated. This model has been renamed Grid.

NavBar

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[ModelID]]) –

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

• items (list[NavLink]) –

  See NavLink. Defaults to [].

NavLink

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

Bases: VizroBaseModel

Navigation in Dashboard to structure Pages.

Parameters:

• pages (NavPagesType) –

  See NavPagesType. Defaults to [].

• nav_selector (Optional[NavSelectorType]) –

  See NavSelectorType. Defaults to None.

Page

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 of the Page.

• description (str) –

  Description for meta tags.

• layout (Optional[LayoutType]) –

  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

Bases: VizroBaseModel

Alter the arguments supplied to any targets on the Page.

Examples:

>>> 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

Bases: VizroBaseModel

Categorical single-option selector RadioItems.

Can be provided to Filter or Parameter.

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 "".

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.RadioItems and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

RangeSlider

Bases: VizroBaseModel

Numeric multi-option selector RangeSlider.

Can be provided to Filter or Parameter.

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[Union[float, int], str]]) –

  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 "".

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dcc.RangeSlider and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dcc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Slider

Bases: VizroBaseModel

Numeric single-option selector Slider.

Can be provided to Filter or Parameter.

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[Union[float, int], str]]) –

  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 "".

• description (Optional[Tooltip]) –

  Optional markdown string that adds an icon next to the title. Hovering over the icon shows a tooltip with the provided description. Defaults to None.

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dcc.Slider and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dcc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Table

Bases: VizroBaseModel

Wrapper for dash_table.DataTable to visualize tables in dashboard.

Parameters:

• type (Literal['table']) –

  Defaults to "table".

• figure (CapturedCallable) –

  Function that returns a Dash DataTable. See vizro.tables.

• title (str) –

  Title of the Table. Defaults to "".

• header (str) –

  Markdown text positioned below the Table.title. Follows the CommonMark specification. Ideal for adding supplementary information such as subtitles, descriptions, or additional context. Defaults to "".

• footer (str) –

  Markdown text positioned below the Table. Follows the CommonMark specification. Ideal for providing further details such as sources, disclaimers, or additional notes. Defaults to "".

• actions (list[ActionType]) –

  See ActionType. Defaults to [].

Tabs

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.

Text

Bases: VizroBaseModel

Creates a text component based on Markdown syntax.

Parameters:

• type (Literal['text']) –

  Defaults to "text".

• text (str) –

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

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dcc.Markdown and overwrite any defaults chosen by the Vizro team. This may have unexpected behavior. Visit the dcc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

Tooltip

Bases: VizroBaseModel

A tooltip that displays text when hovering over an icon.

Parameters:

• text (str) –

  Markdown string for text shown when hovering over the icon. Should adhere to the CommonMark Spec.

• icon (str) –

  Icon name from Google Material icons library.

• extra (Optional[dict[str, Any]]) –

  Extra keyword arguments that are passed to dbc.Tooltip and overwrite any chosen by the Vizro team. This may have unexpected behavior. Visit the dbc documentation to see all available arguments. Not part of the official Vizro schema and the underlying component may change in the future. Defaults to {}.

VizroBaseModel

Bases: BaseModel

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

Parameters:

• id (ModelID) –

  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.

ActionType module-attribute

ActionType = Annotated[Union[Annotated['Action', Tag('action')], Annotated['export_data', Tag('export_data')], Annotated['filter_interaction', Tag('filter_interaction')], SkipJsonSchema[Annotated['_filter', Tag('_filter')]], SkipJsonSchema[Annotated['_parameter', Tag('_parameter')]], SkipJsonSchema[Annotated['_on_page_load', Tag('_on_page_load')]]], Field(discriminator=Discriminator(_get_action_discriminator), description='Action.')]

Discriminated union. Type of action: Action, export_data or filter_interaction.

ComponentType module-attribute

ComponentType = Annotated[Union['AgGrid', 'Button', 'Card', 'Container', 'Figure', 'Graph', 'Text', '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.

LayoutType module-attribute

LayoutType = Annotated[Union[Annotated['Grid', Tag('grid')], Annotated['Flex', Tag('flex')], Annotated['Layout', Tag('legacy_layout')]], Field(discriminator=Discriminator(_get_layout_discriminator), description='Type of layout to place components on the page.')]

Discriminated union. Type of layout to place components on the page: Grid or Flex.

ModelID module-attribute

ModelID = str

Represents a Vizro model ID.

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[ModelID], dict[str, list[ModelID]]]

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, Actions or Figures 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, custom actions, or custom figures.

core_validation staticmethod

core_validation(value)

Core validation logic.

JsonSchemaExtraType

Bases: TypedDict

Type that specifies the extra information needed to parse a CapturedCallable from JSON/YAML.

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 five possible modes: "graph", "table", "ag_grid", "figure" and "action".

Parameters:

• mode (Literal['graph', 'action', 'table', 'ag_grid', 'figure']) –

  The mode of the captured callable. Valid modes are "graph", "table", "ag_grid", "figure" and "action".

Examples:

>>> @capture("graph")
>>> def graph_function():
>>>     ...
>>> @capture("table")
>>> def table_function():
>>>     ...
>>> @capture("ag_grid")
>>> def ag_grid_function():
>>>     ...
>>> @capture("figure")
>>> def figure_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("figure"), you can refer to the guide on figures. For further help on the use of @capture("action"), you can refer to the guide on custom actions.

validate_captured_callable

validate_captured_callable(cls, value, info)

Reusable validator for the figure argument of Figure like models.