Skip to content

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) –
  • 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.

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-selector Checklist to be provided to Filter.

Parameters:

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

Dropdown

Dropdown(**data)

Bases: VizroBaseModel

Categorical multi-selector Dropdown to be provided to Filter.

Parameters:

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:

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(**data)

Bases: VizroBaseModel

Icon to be used in Navigation Bar of Dashboard.

Parameters:

Navigation

Navigation(**data)

Bases: VizroBaseModel

Navigation in Dashboard to structure Pages.

Parameters:

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-selector RadioItems to be provided to Filter.

Parameters:

RangeSlider

RangeSlider(**data)

Bases: VizroBaseModel

Numeric multi-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-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 table components to visualize in dashboard.

Parameters:

  • type (Literal['table']) –

    Defaults to "table".

  • figure (CapturedCallable) –

    Table like object to be displayed. Current choices include: 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['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 or Graph.

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

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[OptionsDictType]]

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

SelectorType module-attribute

SelectorType = Annotated[Union['Checklist', '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, Dropdown, RadioItems, RangeSlider or Slider.

SingleValueType module-attribute

SingleValueType = Union[StrictBool, float, str]

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][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][custom-table] or [custom actions][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 three possible modes: "graph", "table" and "action".

Examples >>> @capture("graph") >>> def graph_function(): >>> ... >>> @capture("table") >>> def table_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"), 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.