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 1.0.0. Use the more powerful and flexible set_controls.

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 `deprecated` `pydantic-model`

Deprecated

set_control is deprecated and will not exist in Vizro 1.0.0 (https://vizro.readthedocs.io/en/stable/pages/API-reference/deprecations/#set_control-action). Use set_controls with controls as a list of ids instead.

Deprecated. Use set_controls with controls as a list of ids instead.

Show JSON schema:

{
  "$defs": {
    "JsonValue": {}
  },
  "additionalProperties": false,
  "deprecated": true,
  "description": "Deprecated. Use [`set_controls`][vizro.actions.set_controls] with `controls` as a list of ids instead.",
  "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"
    },
    "value": {
      "$ref": "#/$defs/JsonValue",
      "default": null,
      "description": "Value to take from the trigger and send to the target control(s). Its format depends on the triggering model (see the list above): for `Graph`/`AgGrid` it is an extraction directive (a column name or lookup) and is required; for `Figure`/`Card`/`Button` it is the literal value to set, and `value=None` resets the target control(s) to their default value. It may be omitted (defaults to `None`) only when a control's own selector syncs to another control, where `value` is ignored and the selector's live value is used instead."
    },
    "control": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ],
      "description": "Filter or Parameter component id(s) to be affected by the trigger. Provide a single id or a list of ids. Deprecated: use `set_controls` with `controls` instead.",
      "title": "Control"
    }
  },
  "required": [
    "control"
  ],
  "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

value

Value to take from the trigger and send to the target control(s). Its format depends on the triggering model (see the list above): for Graph/AgGrid it is an extraction directive (a column name or lookup) and is required; for Figure/Card/Button it is the literal value to set, and value=None resets the target control(s) to their default value. It may be omitted (defaults to None) only when a control's own selector syncs to another control, where value is ignored and the selector's live value is used instead.

TYPE: JsonValue DEFAULT: None

control

Filter or Parameter component id(s) to be affected by the trigger. Provide a single id or a list of ids. Deprecated: use set_controls with controls instead.

TYPE: ModelID | list[ModelID] DEFAULT: required

controls

Populated from the deprecated control argument.

TYPE: SkipJsonSchema[ModelID | list[ModelID]] DEFAULT: []

set_controls `pydantic-model`

Sets the value of one or more controls, which then update their targets.

Usage documentation

Graph and table interactions

controls is one or more control ids: pass a single id, or a list of ids to set several controls from a single trigger (for example, one graph click that cross-filters multiple filters, or one selector that syncs several controls). A single id is normalized to a list internally. The same value is sent to every targeted control and is reshaped to each control's own selector.

The following Vizro models can be a source of set_controls:

AgGrid: triggers set_controls 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_controls 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 controls:
- 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_controls when the user clicks on the figure. value specifies a literal value to set controls to.
Button: triggers set_controls when the user clicks on the button. value specifies a literal value to set controls to.
Card: triggers set_controls when the user clicks on the card. value specifies a literal value to set controls to.

value is required for Graph and AgGrid (it is the directive for what to extract from the click). For Figure, Card, and Button it is the literal to set, and value=None resets the target control(s) to their default value. value may be omitted only when a control's own selector syncs to another control (via that control's targets): the sync uses the selector's live value and ignores value.

an AG Grid Table as trigger

import vizro.actions as va

vm.Table(
    figure=dash_ag_grid(iris),
    actions=va.set_controls(controls=["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_controls(controls=["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_controls(controls=["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_controls(controls=["target_control"], value="A"),
)

Button as trigger

import vizro.actions as va

vm.Button(
    text="Click to set control to A",
    actions=va.set_controls(controls=["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_controls(controls=["target_control"], value="A"),
)

target multiple controls at once

import vizro.actions as va

vm.Graph(
    figure=px.scatter(iris, x="sepal_width", y="sepal_length", custom_data="species"),
    actions=va.set_controls(controls=["target_control_1", "target_control_2"], value="species"),
)

a control selector as trigger (no value needed)

A control's own selector can be the source. Here a bare RadioItems (whitelisted as a page component with add_type) syncs its selected value to two filters. value is omitted: a selector sync sends the selector's own live value, so there is nothing to specify.

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

vm.Page.add_type("components", vm.RadioItems)  # allow a bare selector as a page component

vm.RadioItems(
    options=["setosa", "versicolor", "virginica"],
    actions=va.set_controls(controls=["species_filter_1", "species_filter_2"]),
)

Show JSON schema:

{
  "$defs": {
    "JsonValue": {}
  },
  "additionalProperties": false,
  "description": "Sets the value of one or more controls, which then update their targets.\n\nAbstract: Usage documentation\n    [Graph and table interactions](../user-guides/graph-table-actions.md)\n\n`controls` is one or more control ids: pass a single id, or a list of ids to set several controls from a single\ntrigger (for example, one graph click that cross-filters multiple filters, or one selector that syncs several\ncontrols). A single id is normalized to a list internally. The same `value` is sent to every targeted control and\nis reshaped to each control's own selector.\n\nThe following Vizro models can be a source of `set_controls`:\n\n* [`AgGrid`][vizro.models.AgGrid]: triggers `set_controls` 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_controls` 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 `controls`:\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_controls` when the user clicks on the figure. `value` specifies a\nliteral value to set `controls` to.\n* [`Button`][vizro.models.Button]: triggers `set_controls` when the user clicks on the button. `value` specifies a\nliteral value to set `controls` to.\n* [`Card`][vizro.models.Card]: triggers `set_controls` when the user clicks on the card. `value` specifies a\nliteral value to set `controls` to.\n\n`value` is required for `Graph` and `AgGrid` (it is the directive for what to extract from the click). For\n`Figure`, `Card`, and `Button` it is the literal to set, and `value=None` resets the target control(s) to their\ndefault value. `value` may be omitted only when a control's own selector syncs to another control (via that\ncontrol's `targets`): the sync uses the selector's live value and ignores `value`.\n\nExample: an AG Grid `Table` as trigger\n    ```python\n    import vizro.actions as va\n\n    vm.Table(\n        figure=dash_ag_grid(iris),\n        actions=va.set_controls(controls=[\"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_controls(controls=[\"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_controls(controls=[\"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_controls(controls=[\"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_controls(controls=[\"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_controls(controls=[\"target_control\"], value=\"A\"),\n    )\n    ```\n\nExample: target multiple controls at once\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_controls(controls=[\"target_control_1\", \"target_control_2\"], value=\"species\"),\n    )\n    ```\n\nExample: a control selector as trigger (no `value` needed)\n    A control's own selector can be the source. Here a bare `RadioItems` (whitelisted as a page component with\n    `add_type`) syncs its selected value to two filters. `value` is omitted: a selector sync sends the selector's\n    own live value, so there is nothing to specify.\n    ```python\n    import vizro.models as vm\n    import vizro.actions as va\n\n    vm.Page.add_type(\"components\", vm.RadioItems)  # allow a bare selector as a page component\n\n    vm.RadioItems(\n        options=[\"setosa\", \"versicolor\", \"virginica\"],\n        actions=va.set_controls(controls=[\"species_filter_1\", \"species_filter_2\"]),\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_controls",
      "default": "set_controls",
      "title": "Type",
      "type": "string"
    },
    "controls": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ],
      "description": "Filter or Parameter component id(s) to be affected by the trigger. Provide a single id, or a list of ids to set several controls at once. Each control can be on the same page as the trigger or on a different page: a different-page control is kept in sync through the internal `vizro_controls_store`, and its new value is applied when that page is opened.",
      "title": "Controls"
    },
    "value": {
      "$ref": "#/$defs/JsonValue",
      "default": null,
      "description": "Value to take from the trigger and send to the target control(s). Its format depends on the triggering model (see the list above): for `Graph`/`AgGrid` it is an extraction directive (a column name or lookup) and is required; for `Figure`/`Card`/`Button` it is the literal value to set, and `value=None` resets the target control(s) to their default value. It may be omitted (defaults to `None`) only when a control's own selector syncs to another control, where `value` is ignored and the selector's live value is used instead."
    }
  },
  "required": [
    "controls"
  ],
  "title": "set_controls",
  "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

controls

Filter or Parameter component id(s) to be affected by the trigger. Provide a single id, or a list of ids to set several controls at once. Each control can be on the same page as the trigger or on a different page: a different-page control is kept in sync through the internal vizro_controls_store, and its new value is applied when that page is opened.

TYPE: ModelID | list[ModelID] DEFAULT: required

value

Value to take from the trigger and send to the target control(s). Its format depends on the triggering model (see the list above): for Graph/AgGrid it is an extraction directive (a column name or lookup) and is required; for Figure/Card/Button it is the literal value to set, and value=None resets the target control(s) to their default value. It may be omitted (defaults to None) only when a control's own selector syncs to another control, where value is ignored and the selector's live value is used instead.

TYPE: JsonValue DEFAULT: None

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

update_targets `pydantic-model`

Refreshes target figures on the page by re-applying the page's controls.

Re-runs the targeted charts, tables and figures against the current values of the page's filters and parameters. This is the shared mechanism behind Filter, Parameter and on-page-load, and can also be used directly (for example on a Button) to refresh figures on demand.

Usage documentation

How to apply controls with a button

Example

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

vm.Button(text="Apply controls", actions=va.update_targets(targets=["my_graph"]))

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Refreshes target figures on the page by re-applying the page's controls.\n\nRe-runs the targeted charts, tables and figures against the current values of the page's filters and parameters.\nThis is the shared mechanism behind `Filter`, `Parameter` and on-page-load, and can also be used directly (for\nexample on a `Button`) to refresh figures on demand.\n\nAbstract: Usage documentation\n    [How to apply controls with a button](../user-guides/controls.md#apply-controls-with-a-button)\n\nExample:\n    ```python\n    import vizro.actions as va\n    import vizro.models as vm\n\n    vm.Button(text=\"Apply controls\", actions=va.update_targets(targets=[\"my_graph\"]))\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_targets",
      "default": "update_targets",
      "title": "Type",
      "type": "string"
    },
    "targets": {
      "default": [],
      "description": "Component ids to refresh. Figures and dynamic filters on the page are valid targets. If none are given then all figures and dynamic filters on the page are targeted.",
      "items": {
        "type": "string"
      },
      "title": "Targets",
      "type": "array"
    }
  },
  "title": "update_targets",
  "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

Component ids to refresh. Figures and dynamic filters on the page are valid targets. If none are given then all figures and dynamic filters on the page are targeted.

TYPE: list[ModelID] DEFAULT: []

Actions

vizro.actions

export_data pydantic-model

filter_interaction deprecated pydantic-model

set_control deprecated pydantic-model

set_controls pydantic-model

show_notification pydantic-model

update_notification pydantic-model

update_targets pydantic-model

export_data `pydantic-model`

filter_interaction `deprecated` `pydantic-model`

set_control `deprecated` `pydantic-model`

set_controls `pydantic-model`

show_notification `pydantic-model`

update_notification `pydantic-model`

update_targets `pydantic-model`