Skip to content

How to use Actions

This guide shows you how to use actions, a concept that is similar, but not identical, to callbacks in Dash. Many components of a dashboard (e.g. Graph or Button) have an optional actions argument, where you can enter the Action model.

In a nutshell, using the Action model together with an action function allows you to create complex functionality on a variety of triggers in your dashboard. There is already a range of reusable action functions available.

Overview of currently available pre-defined action functions

Pre-defined actions

To attach an action to a component, you must enter the Action model into the component's action argument. You can then add a desired pre-defined action function into the function argument of the Action.

Note on Trigger

Currently each component has one pre-defined trigger property. A trigger property is an attribute of the component that triggers a configured action (e.g. for the Button it is n_click).

The below sections are guides on how to leverage pre-defined action functions.

Export data

In order to enable downloading data, you can add the export_data action function to the Button component. Hence, as a result, when a dashboard user now clicks the button, all data on the page will be downloaded.

export_data

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.actions import export_data

iris = px.data.iris()

page = vm.Page(
    title="Using actions",
    components=[
        vm.Graph(
            figure=px.scatter(iris, x="petal_length", y="sepal_length", color="sepal_width"),
        ),
        vm.Graph(
            figure=px.histogram(iris, x="petal_length", color="species"),
        ),
        vm.Button(
            text="Export data",
            actions=[
                vm.Action(
                    function=export_data()
                ),
            ],
        ),
    ],
    controls=[
        vm.Filter(column="species"),
    ],
)

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
  - components:
    - type: graph
      figure:
        _target_: scatter
        data_frame: iris
        color: sepal_width
        x: petal_length
        y: sepal_length
    - type: graph
      figure:
        _target_: histogram
        data_frame: iris
        color: species
        x: petal_length
    - type: button
      text: Export data
      id: export_data_button
      actions:
       - function:
            _target_: export_data
    controls:
      - type: filter
        column: species
    title: Exporting

Graph

Filter data by clicking on chart

To enable filtering when clicking on data in a source chart, you can add the filter_interaction action function to the Graph or Table component. The filter_interaction is currently configured to be triggered on click only.

To configure this chart interaction follow the steps below:

  1. Add the action function to the source Graph or Table component and a list of IDs of the target charts into targets.
    actions=[vm.Action(function=filter_interaction(targets=["scatter_relation_2007"]))]
    
  2. If the source chart is Graph, enter the filter columns in the custom_data argument of the underlying source chart function.
    Graph(figure=px.scatter(..., custom_data=["continent"]))
    
    Selecting a data point with a corresponding value of "Africa" in the continent column will result in filtering the dataset of target charts to show only entries with "Africa" in the continent column. The same applies when providing multiple columns in custom_data.

Tip

  • You can reset your chart interaction filters by refreshing the page
  • You can create a "self-interaction" by providing the source chart id as its own target

Here is an example of how to configure a chart interaction when the source is a Graph component.

Graph filter_interaction

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.actions import filter_interaction

df_gapminder = px.data.gapminder().query("year == 2007")

dashboard = vm.Dashboard(
    pages=[
        vm.Page(
            title="Filter interaction",
            components=[
                vm.Graph(
                    figure=px.box(
                        df_gapminder,
                        x="continent",
                        y="lifeExp",
                        color="continent",
                        custom_data=["continent"],
                    ),
                    actions=[vm.Action(function=filter_interaction(targets=["scatter_relation_2007"]))],
                ),
                vm.Graph(
                    id="scatter_relation_2007",
                    figure=px.scatter(
                        df_gapminder,
                        x="gdpPercap",
                        y="lifeExp",
                        size="pop",
                        color="continent",
                    ),
                ),
            ],
            controls=[vm.Filter(column='continent')]
        ),
    ]
)

Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
  - components:
    - type: graph
      figure:
        _target_: box
        data_frame: gapminder
        color: continent
        x: continent
        y: lifeExp
        custom_data:
          - continent
      actions:
       - function:
            _target_: filter_interaction
            targets:
              - scatter_relation_2007
    - type: graph
      id: scatter_relation_2007
      figure:
        _target_: scatter
        data_frame: gapminder
        color: continent
        x: gdpPercap
        y: lifeExp
        size: pop
    controls:
      - column: continent
        type: filter
    title: Filter interaction

Graph2

Here is an example of how to configure a chart interaction when the source is a Table component.

Table filter_interaction

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.actions import filter_interaction
from vizro.tables import dash_data_table

df_gapminder = px.data.gapminder().query("year == 2007")

dashboard = vm.Dashboard(
    pages=[
        vm.Page(
            title="Filter interaction",
            components=[
                vm.Table(
                    figure=dash_data_table(id="dash_datatable_id", data_frame=df_gapminder),
                    actions=[
                        vm.Action(function=filter_interaction(targets=["scatter_relation_2007"]))
                    ],
                ),
                vm.Graph(
                    id="scatter_relation_2007",
                    figure=px.scatter(
                        df_gapminder,
                        x="gdpPercap",
                        y="lifeExp",
                        size="pop",
                        color="continent",
                    ),
                ),
            ],
            controls=[vm.Filter(column='continent')]
        ),
    ]
)

Vizro().build(dashboard).run()
# Still requires a .py to register data connector in Data Manager and parse yaml configuration
# See yaml_version example
pages:
  - components:
    - type: table
      figure:
        _target_: dash_data_table
        data_frame: gapminder_2007
        id: dash_datatable_id
      actions:
       - function:
            _target_: filter_interaction
            targets:
              - scatter_relation_2007
    - type: graph
      id: scatter_relation_2007
      figure:
        _target_: scatter
        data_frame: gapminder_2007
        color: continent
        x: gdpPercap
        y: lifeExp
        size: pop
    controls:
      - column: continent
        type: filter
    title: Filter interaction

Table

Pre-defined actions customization

Many pre-defined actions are customizable which helps to achieve more specific desired goal. For specific options, please refer to the API reference on this topic.

Actions chaining

The actions parameter for the different screen components accepts a List of Action models. This means that it's possible to set a list of actions that will be executed by triggering only one component. The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed.

Actions chaining

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.actions import export_data

iris = px.data.iris()

page = vm.Page(
    title="Using actions",
    components=[
        vm.Graph(
            id="scatter",
            figure=px.scatter(iris, x="petal_length", y="sepal_length", color="sepal_width"),
        ),
        vm.Graph(
            id="hist",
            figure=px.histogram(iris, x="petal_length", color="species"),
        ),
        vm.Button(
            text="Export data",
            actions=[
                vm.Action(
                    function=export_data(
                        targets=["scatter"],
                    )
                ),
                vm.Action(
                    function=export_data(
                        targets=["hist"],
                        file_format="xlsx",
                    )
                ),
            ],
        ),
    ],
    controls=[
        vm.Filter(column="species"),
    ],
)

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
pages:
  - components:
    - type: graph
      id: scatter
      figure:
        _target_: scatter
        data_frame: iris
        color: sepal_width
        x: petal_length
        y: sepal_length
    - type: graph
      id: hist
      figure:
        _target_: histogram
        data_frame: iris
        color: species
        x: petal_length
    - type: button
      text: Export data
      id: export_data_button
      actions:
        - function:
            _target_: export_data
            targets:
             - scatter
        - function:
            _target_: export_data
            targets:
             - hist
            file_format: xlsx
    controls:
      - type: filter
        column: species
    title: Exporting

Graph3

To enhance existing actions, please see our How-to-guide on creating custom actions.