Skip to content

How to use graphs

This guide shows you how to use graphs to visualize your data in the dashboard.

The Graph model is the most used component in many dashboards, allowing you to visualize data in a variety of ways.

To add a Graph to your page, do the following:

  1. insert the Graph model into the components argument of the Page model
  2. enter any of the currently available charts of the open source library plotly.express into the figure argument

Note

To use the plotly.express chart in a Vizro dashboard, you need to import it as import vizro.plotly.express as px. This leaves any of the plotly.express functionality untouched yet enables direct insertion into the Graph model as is.

Note also that the plotly.express chart needs to have a data_frame argument. In case you require a chart without a data_frame argument (for example, the imshow chart), refer to our guide on custom charts.

Insert Plotly chart

Graph

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

df = px.data.iris()

page = vm.Page(
    title="My first page",
    components=[
        vm.Graph(
            figure=px.scatter_matrix(
                df, dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"], color="species"
            ),
        ),
    ],
)

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

Vizro().build(dashboard).run()

Run and edit this code in Py.Cafe

# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
  - components:
      - figure:
          _target_: scatter_matrix
          color: species
          data_frame: iris
          dimensions: [sepal_length, sepal_width, petal_length, petal_width]
        type: graph
    title: My first page

Graph

In the Python example we directly inserted the pandas DataFrame df into figure=px.scatter_matrix(df, ...). This is one way to supply data to a chart. For the YAML version, we refer to the data source by name as data_frame: iris. For a full explanation of the different methods you can use to send data to your dashboard, see our guide to using data in Vizro.

Customize Plotly chart

You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:

  • using post-update methods like update_layout, update_xaxes, update_traces, or
  • by creating a custom plotly.graph_objects.Figure() object and manually adding traces with add_trace.

For more details, refer to our user guide on custom chart and the Plotly documentation on updating figures.

The Graph accepts a title, header and footer argument. This is useful for context on the data being displayed, or for adding a description of the data.

  • title: Displayed as an H3 header, useful for summarizing the main topic or insight of the component.
  • header: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
  • footer: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.

Note

Although you can directly give a title to the Plotly Express chart, we recommend using Graph.title for proper alignment with other components on the screen.

Formatted Graph

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

iris = px.data.iris()

page = vm.Page(
    title="Formatted Graph",
    components=[
        vm.Graph(
            figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species"),
            title="Relationships between Sepal Width and Sepal Length",
            header="""
                Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
                types. The Setosa type is easily identifiable by its short and wide sepals.

                However, there is still overlap between the Versicolor and Virginica types when considering only sepal
                width and length.
                """,
            footer="""SOURCE: **Plotly iris data set, 2024**""",
        ),
    ],
)
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()

Run and edit this code in Py.Cafe

# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
  - components:
      - figure:
          _target_: scatter
          x: sepal_width
          y: sepal_length
          color: species
          data_frame: iris
        title: Relationships between Sepal Width and Sepal Length
        header: |
          Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
          types. The Setosa type is easily identifiable by its short and wide sepals.

          However, there is still overlap between the Versicolor and Virginica types when considering only sepal
          width and length.
        footer: |
          SOURCE: **Plotly iris data set, 2024**
        type: graph
    title: Formatted Graph

FormattedGraph