Actions

vizro.actions

Built-in actions, typically aliased as va using import vizro.actions as va.

Usage documentation

How to use actions

export_data `pydantic-model`

Exports data of target charts, tables and figures.

Usage documentation

How to export data

Example

import vizro.actions as va

vm.Button(
    text="Export data",
    actions=va.export_data(targets=["graph_id", "table_id"], file_format="xlsx"),
)

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Exports data of target charts, tables and figures.\n\nAbstract: Usage documentation\n    [How to export data](user-guides/data-actions.md#export-data)\n\nExample:\n    ```python\n    import vizro.actions as va\n\n    vm.Button(\n        text=\"Export data\",\n        actions=va.export_data(targets=[\"graph_id\", \"table_id\"], file_format=\"xlsx\"),\n    )\n    ```",
  "properties": {
    "id": {
      "description": "ID to identify model. Must be unique throughout the whole dashboard. When no ID is chosen, ID will be automatically generated.",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "const": "export_data",
      "default": "export_data",
      "title": "Type",
      "type": "string"
    },
    "targets": {
      "default": [],
      "description": "List of target component ids for which to download data. If none are given then download data from all components on the page.",
      "items": {
        "type": "string"
      },
      "title": "Targets",
      "type": "array"
    },
    "file_format": {
      "default": "csv",
      "description": "Format of downloaded files.",
      "enum": [
        "csv",
        "xlsx"
      ],
      "title": "File Format",
      "type": "string"
    }
  },
  "title": "export_data",
  "type": "object"
}

Fields:

Name

Description

id

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

TYPE: str DEFAULT: generated uuid

targets

List of target component ids for which to download data. If none are given then download data from all components on the page.

TYPE: list[ModelID] DEFAULT: []

file_format

Format of downloaded files.

TYPE: Literal['csv', 'xlsx'] DEFAULT: 'csv'

filter_interaction `deprecated` `pydantic-model`

Deprecated

filter_interaction is deprecated and will not exist in Vizro 0.2.0. Use the more powerful and flexible set_control.

Filters targeted graph, tables and figures when a source graph or table is clicked.

Show JSON schema:

{
  "additionalProperties": false,
  "deprecated": true,
  "description": "Filters targeted graph, tables and figures when a source graph or table is clicked.",
  "properties": {
    "id": {
      "description": "ID to identify model. Must be unique throughout the whole dashboard. When no ID is chosen, ID will be automatically generated.",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "const": "filter_interaction",
      "default": "filter_interaction",
      "title": "Type",
      "type": "string"
    },
    "targets": {
      "default": [],
      "description": "Target component IDs.",
      "items": {
        "type": "string"
      },
      "title": "Targets",
      "type": "array"
    }
  },
  "title": "filter_interaction",
  "type": "object"
}

Fields:

Name

Description

id

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

TYPE: str DEFAULT: generated uuid

targets

Target component IDs.

TYPE: list[ModelID] DEFAULT: []

set_control `pydantic-model`

Sets the value of a control, which then updates its targets.

Usage documentation

Graph and table interactions

The following Vizro models can be a source of set_control:

AgGrid: triggers set_control when cellClicked or selectedRows changes (for example after a cell click or when the row selection changes). value can be:
- "cell", "column", or "row" to use the clicked cell's value, column id, or row id respectively.
- Any other string to treat as a column name, taking values from the selected row(s).
- Graph: triggers set_control when the user clicks on data in the graph. value is a string that can be used in two ways to specify how to set control:
- Column from which to take the value. This requires you to set custom_data in the graph's figure function.
- String to traverse a Box that contains the trigger data clickData["points"][0]. This is typically useful for a positional variable, for example "x", and does not require setting custom_data.
Figure: triggers set_control when the user clicks on the figure. value specifies a literal value to set control to.
Button: triggers set_control when the user clicks on the button. value specifies a literal value to set control to.
Card: triggers set_control when the user clicks on the card. value specifies a literal value to set control to.

AgGrid as trigger

import vizro.actions as va

vm.AgGrid(
    figure=dash_ag_grid(iris),
    actions=va.set_control(control="target_control", value="species"),
)

Graph as trigger with custom_data

import vizro.actions as va

vm.Graph(
    figure=px.scatter(iris, x="sepal_width", y="sepal_length", custom_data="species"),
    actions=va.set_control(control="target_control", value="species"),
)

Graph as trigger without custom_data

import vizro.actions as va

vm.Graph(
    figure=px.box(iris, x="species", y="sepal_length"),
    actions=va.set_control(control="target_control", value="x"),
)

Figure as trigger

import vizro.actions as va
from vizro.figures import kpi_card

vm.Figure(
    figure=kpi_card(tips, value_column="tip", title="Click KPI to set control to A"),
    actions=va.set_control(control="target_control", value="A"),
)

Button as trigger

import vizro.actions as va

vm.Button(
    text="Click to set control to A",
    actions=va.set_control(control="target_control", value="A"),
)

Card as trigger

import vizro.actions as va

vm.Card(
    title="Click Card to set control to A",
    actions=va.set_control(control="target_control", value="A"),
)

Show JSON schema:

{
  "$defs": {
    "JsonValue": {}
  },
  "additionalProperties": false,
  "description": "Sets the value of a control, which then updates its targets.\n\nAbstract: Usage documentation\n    [Graph and table interactions](user-guides/graph-table-actions.md)\n\nThe following Vizro models can be a source of `set_control`:\n\n* [`AgGrid`][vizro.models.AgGrid]: triggers `set_control` when `cellClicked` or `selectedRows` changes (for example\nafter a cell click or when the row selection changes). `value` can be:\n\n    * `\"cell\"`, `\"column\"`, or `\"row\"` to use the clicked cell's value, column id, or row id respectively.\n    * Any other string to treat as a column name, taking values from the selected row(s).\n* [`Graph`][vizro.models.Graph]: triggers `set_control` when the user clicks on data in the graph. `value` is a\nstring that can be used in two ways to specify how to set `control`:\n\n    * Column from which to take the value. This requires you to set `custom_data` in the graph's `figure` function.\n    * String to [traverse a Box](https://github.com/cdgriffith/Box/wiki/Types-of-Boxes#box-dots) that contains the\n    trigger data [`clickData[\"points\"][0]`](https://dash.plotly.com/interactive-graphing). This is typically\n    useful for a positional variable, for example `\"x\"`, and does not require setting `custom_data`.\n\n* [`Figure`][vizro.models.Figure]: triggers `set_control` when the user clicks on the figure. `value` specifies a\nliteral value to set `control` to.\n* [`Button`][vizro.models.Button]: triggers `set_control` when the user clicks on the button. `value` specifies a\nliteral value to set `control` to.\n* [`Card`][vizro.models.Card]: triggers `set_control` when the user clicks on the card. `value` specifies a\nliteral value to set `control` to.\n\nExample: `AgGrid` as trigger\n    ```python\n    import vizro.actions as va\n\n    vm.AgGrid(\n        figure=dash_ag_grid(iris),\n        actions=va.set_control(control=\"target_control\", value=\"species\"),\n    )\n    ```\n\nExample: `Graph` as trigger with `custom_data`\n    ```python\n    import vizro.actions as va\n\n    vm.Graph(\n        figure=px.scatter(iris, x=\"sepal_width\", y=\"sepal_length\", custom_data=\"species\"),\n        actions=va.set_control(control=\"target_control\", value=\"species\"),\n    )\n    ```\n\nExample: `Graph` as trigger without `custom_data`\n    ```python\n    import vizro.actions as va\n\n    vm.Graph(\n        figure=px.box(iris, x=\"species\", y=\"sepal_length\"),\n        actions=va.set_control(control=\"target_control\", value=\"x\"),\n    )\n    ```\n\nExample: `Figure` as trigger\n    ```python\n    import vizro.actions as va\n    from vizro.figures import kpi_card\n\n    vm.Figure(\n        figure=kpi_card(tips, value_column=\"tip\", title=\"Click KPI to set control to A\"),\n        actions=va.set_control(control=\"target_control\", value=\"A\"),\n    )\n    ```\n\nExample: `Button` as trigger\n    ```python\n    import vizro.actions as va\n\n    vm.Button(\n        text=\"Click to set control to A\",\n        actions=va.set_control(control=\"target_control\", value=\"A\"),\n    )\n    ```\n\nExample: `Card` as trigger\n    ```python\n    import vizro.actions as va\n\n    vm.Card(\n        title=\"Click Card to set control to A\",\n        actions=va.set_control(control=\"target_control\", value=\"A\"),\n    )\n    ```",
  "properties": {
    "id": {
      "description": "ID to identify model. Must be unique throughout the whole dashboard. When no ID is chosen, ID will be automatically generated.",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "const": "set_control",
      "default": "set_control",
      "title": "Type",
      "type": "string"
    },
    "control": {
      "description": "Filter or Parameter component id to be affected by the trigger. If the control is on a different page to the trigger, then it must have `show_in_url=True`.",
      "title": "Control",
      "type": "string"
    },
    "value": {
      "$ref": "#/$defs/JsonValue",
      "description": "Value to take from trigger and send to the `target`. Format depends on the model that triggers `set_control`."
    }
  },
  "required": [
    "control",
    "value"
  ],
  "title": "set_control",
  "type": "object"
}

Fields:

Name

Description

id

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

TYPE: str DEFAULT: generated uuid

control

Filter or Parameter component id to be affected by the trigger. If the control is on a different page to the trigger, then it must have show_in_url=True.

TYPE: ModelID DEFAULT: required

value

Value to take from trigger and send to the target. Format depends on the model that triggers set_control.

TYPE: JsonValue DEFAULT: required

show_notification `pydantic-model`

Shows a notification message.

Usage documentation

Notifications

Example

import vizro.actions as va
import vizro.models as vm

vm.Button(
    text="Save",
    actions=va.show_notification(
        title="Useful information",
        text="This is some useful information that you should know.",
    ),
)

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Shows a notification message.\n\nAbstract: Usage documentation\n    [Notifications](user-guides/notification-actions.md)\n\nExample:\n    ```python\n    import vizro.actions as va\n    import vizro.models as vm\n\n    vm.Button(\n        text=\"Save\",\n        actions=va.show_notification(\n            title=\"Useful information\",\n            text=\"This is some useful information that you should know.\",\n        ),\n    )\n    ```",
  "properties": {
    "id": {
      "description": "ID to identify model. Must be unique throughout the whole dashboard. When no ID is chosen, ID will be automatically generated.",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "const": "show_notification",
      "default": "show_notification",
      "title": "Type",
      "type": "string"
    },
    "text": {
      "description": "Markdown text for the main notification message. Follows the CommonMark specification.",
      "title": "Text",
      "type": "string"
    },
    "variant": {
      "default": "info",
      "description": "Variant that determines color and default icon. If `progress`, the notification will show a loading spinner instead of an icon.",
      "enum": [
        "info",
        "success",
        "warning",
        "error",
        "progress"
      ],
      "title": "Variant",
      "type": "string"
    },
    "title": {
      "default": "",
      "description": "Notification title. Set to `\"\"` to hide the title. Defaults to the capitalized variant name, for example `\"Info\"` for `variant=\"info\"`.",
      "title": "Title",
      "type": "string"
    },
    "icon": {
      "default": "",
      "description": "Icon name from the [Google Material Icon Library](https://fonts.google.com/icons). Ignored if `variant='progress'`. Defaults to the variant-specific icon, for example 'info' for 'info' variant.",
      "title": "Icon",
      "type": "string"
    },
    "auto_close": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "integer"
        }
      ],
      "default": 4000,
      "description": "Auto-close duration in milliseconds. Set to `False` to keep the notification open until the user closes it manually. Default value depends on variant: `4000` for info/success/warning/error, `False` for progress.",
      "title": "Auto Close"
    }
  },
  "required": [
    "text"
  ],
  "title": "show_notification",
  "type": "object"
}

Fields:

Name

Description

id

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

TYPE: str DEFAULT: generated uuid

text

Markdown text for the main notification message. Follows the CommonMark specification.

TYPE: str DEFAULT: required

variant

Variant that determines color and default icon. If progress, the notification will show a loading spinner instead of an icon.

TYPE: Literal['info', 'success', 'warning', 'error', 'progress'] DEFAULT: 'info'

title

Notification title. Set to "" to hide the title. Defaults to the capitalized variant name, for example "Info" for variant="info".

TYPE: str DEFAULT: ''

icon

Icon name from the Google Material Icon Library. Ignored if variant='progress'. Defaults to the variant-specific icon, for example 'info' for 'info' variant.

TYPE: str DEFAULT: ''

auto_close

Auto-close duration in milliseconds. Set to False to keep the notification open until the user closes it manually. Default value depends on variant: 4000 for info/success/warning/error, False for progress.

TYPE: bool | int DEFAULT: 4000

update_notification `pydantic-model`

Updates an existing notification message.

This action updates notifications that were previously created with show_notification. notification must match the id of the original show_notification action.

Usage documentation

Update notification

Example

import vizro.actions as va
import vizro.models as vm

vm.Button(
    text="Save",
    actions=[
        va.show_notification(id="save_notification", text="Saving data...", variant="progress"),
        va.export_data(),
        va.update_notification(
            notification="save_notification", text="Data saved successfully!", variant="success"
        ),
    ],
)

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Updates an existing notification message.\n\nThis action updates notifications that were previously created with\n[`show_notification`][vizro.actions.show_notification]. `notification` must match the `id` of the original\n`show_notification` action.\n\nAbstract: Usage documentation\n    [Update notification](user-guides/notification-actions.md#update-existing-notification)\n\nExample:\n    ```python\n    import vizro.actions as va\n    import vizro.models as vm\n\n    vm.Button(\n        text=\"Save\",\n        actions=[\n            va.show_notification(id=\"save_notification\", text=\"Saving data...\", variant=\"progress\"),\n            va.export_data(),\n            va.update_notification(\n                notification=\"save_notification\", text=\"Data saved successfully!\", variant=\"success\"\n            ),\n        ],\n    )\n    ```",
  "properties": {
    "id": {
      "description": "ID to identify model. Must be unique throughout the whole dashboard. When no ID is chosen, ID will be automatically generated.",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "const": "update_notification",
      "default": "update_notification",
      "title": "Type",
      "type": "string"
    },
    "text": {
      "description": "Markdown text for the main notification message. Follows the CommonMark specification.",
      "title": "Text",
      "type": "string"
    },
    "variant": {
      "default": "info",
      "description": "Variant that determines color and default icon. If `progress`, the notification will show a loading spinner instead of an icon.",
      "enum": [
        "info",
        "success",
        "warning",
        "error",
        "progress"
      ],
      "title": "Variant",
      "type": "string"
    },
    "title": {
      "default": "",
      "description": "Notification title. Set to `\"\"` to hide the title. Defaults to the capitalized variant name, for example `\"Info\"` for `variant=\"info\"`.",
      "title": "Title",
      "type": "string"
    },
    "icon": {
      "default": "",
      "description": "Icon name from the [Google Material Icon Library](https://fonts.google.com/icons). Ignored if `variant='progress'`. Defaults to the variant-specific icon, for example 'info' for 'info' variant.",
      "title": "Icon",
      "type": "string"
    },
    "auto_close": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "integer"
        }
      ],
      "default": 4000,
      "description": "Auto-close duration in milliseconds. Set to `False` to keep the notification open until the user closes it manually. Default value depends on variant: `4000` for info/success/warning/error, `False` for progress.",
      "title": "Auto Close"
    },
    "notification": {
      "description": "Notification to update. Must match the id of the original `show_notification` action.",
      "title": "Notification",
      "type": "string"
    }
  },
  "required": [
    "text",
    "notification"
  ],
  "title": "update_notification",
  "type": "object"
}

Fields:

Name

Description

id

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

TYPE: str DEFAULT: generated uuid

text

Markdown text for the main notification message. Follows the CommonMark specification.

TYPE: str DEFAULT: required

variant

Variant that determines color and default icon. If progress, the notification will show a loading spinner instead of an icon.

TYPE: Literal DEFAULT: 'info'

title

Notification title. Set to "" to hide the title. Defaults to the capitalized variant name, for example "Info" for variant="info".

TYPE: str DEFAULT: ''

icon

Icon name from the Google Material Icon Library. Ignored if variant='progress'. Defaults to the variant-specific icon, for example 'info' for 'info' variant.

TYPE: str DEFAULT: ''

auto_close

Auto-close duration in milliseconds. Set to False to keep the notification open until the user closes it manually. Default value depends on variant: 4000 for info/success/warning/error, False for progress.

TYPE: Union DEFAULT: 4000

notification

Notification to update. Must match the id of the original show_notification action.

TYPE: ModelID DEFAULT: required

Actions

vizro.actions

export_data pydantic-model

filter_interaction deprecated pydantic-model

set_control pydantic-model

show_notification pydantic-model

update_notification pydantic-model

export_data `pydantic-model`

filter_interaction `deprecated` `pydantic-model`

set_control `pydantic-model`

show_notification `pydantic-model`

update_notification `pydantic-model`