Skip to content

How to use figures

This guide shows you how to add any Dash component that needs to be reactive to controls such as filters and parameters. If you want to add a static Dash component to your page, use custom components instead.

Figure provides a flexible foundation for all types of reactive Dash components in Vizro. The Graph, Table and AgGrid models are specific implementations of Figure. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.

If these more specific models already achieve what you need then they should be used in preference to the more generic Figure. Remember that it is possible to supply custom charts to Graph and custom tables to Table.

There are already a few figure functions you can reuse, see the section on KPI cards for more details:

The following flowchart shows what you need to consider when choosing which model to use:

graph TD
  first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
  specific-component([Use the specific component])
  second["`Does your component need to be reactive to controls?`"]
  second-static([Use custom components])
  second-reactive([Use Figure])

  first -- Yes --> specific-component
  first -- No --> second
  second -- No --> second-static
  second -- Yes --> second-reactive

  click specific-component href "../components/"
  click second-static href "../custom-components/"
  click second-reactive href "#how-to-use-figures"

  classDef clickable color:#4051b5;

To add a Figure to your page:

  1. Add the Figure model to the components argument of the Page model.
  2. Use an existing figure function from vizro.figures and pass it to the figure argument of the Figure model.

Use existing figure functions

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.figures import kpi_card  # (1)!

tips = px.data.tips()

page = vm.Page(
    title="KPI card",
    layout=vm.Flex(direction="row"),  # (2)!
    components=[
        vm.Figure(
            figure=kpi_card(
                data_frame=tips,
                value_column="tip",
                value_format="${value:.2f}",
                icon="Shopping Cart",
                title="Average Price",
            )
        )
    ],
    controls=[vm.Filter(column="day", selector=vm.RadioItems())],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()

Run and edit this code in Py.Cafe

  1. For more information, refer to the API reference for kpi_card.
  2. We switch to a Flex layout so that the KPI card only takes up as much space as it needs.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
  - components:
      - figure:
          _target_: kpi_card
          data_frame: tips
          value_column: tip
          value_format: ${value:.2f}
          icon: Shopping Cart
          title: Average Price
        type: figure
    controls:
      - column: day
        type: filter
        selector:
          type: radio_items
    layout:
      direction: row
      type: flex
    title: KPI card

Figure

Key Performance Indicator (KPI) cards

A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro comes with two built-in KPI card functions:

  • kpi_card: A KPI card that shows a single value found by performing an aggregation function (by default, sum) over a specified column. Required arguments are data_frame and value_column.

  • kpi_card_with_reference: A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, sum) over the specified columns. Required arguments are data_frame, value_column and reference_column.

As described in the API reference and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a custom figure.

KPI card variations

/* We define a fixed height and width to ensure uniform styling for all KPI cards. */
.flex-item .card-kpi {
    width: 300px;
    height: 150px;
}

import pandas as pd
import vizro.models as vm
from vizro import Vizro
from vizro.figures import kpi_card, kpi_card_reference  # (1)!

df_kpi = pd.DataFrame({"Actual": [100, 200, 700], "Reference": [100, 300, 500], "Category": ["A", "B", "C"]})

example_cards = [
    kpi_card(data_frame=df_kpi, value_column="Actual", title="KPI with value"),
    kpi_card(data_frame=df_kpi, value_column="Actual", title="KPI with aggregation", agg_func="median"),
    kpi_card(
        data_frame=df_kpi,
        value_column="Actual",
        title="KPI with formatting",
        value_format="${value:.2f}",
    ),
    kpi_card(
        data_frame=df_kpi,
        value_column="Actual",
        title="KPI with icon",
        icon="Shopping Cart",
    ),
]

example_reference_cards = [
    kpi_card_reference(
        data_frame=df_kpi,
        value_column="Actual",
        reference_column="Reference",
        title="KPI reference (pos)",
    ),
    kpi_card_reference(
        data_frame=df_kpi,
        value_column="Actual",
        reference_column="Reference",
        agg_func="median",
        title="KPI reference (neg)",
    ),
    kpi_card_reference(
        data_frame=df_kpi,
        value_column="Actual",
        reference_column="Reference",
        title="KPI reference with formatting",
        value_format="{value:.2f}€",
        reference_format="{delta:+.2f}€ vs. last year ({reference:.2f}€)",
    ),
    kpi_card_reference(
        data_frame=df_kpi,
        value_column="Actual",
        reference_column="Reference",
        title="KPI reference with icon",
        icon="Shopping Cart",
    ),
    kpi_card_reference(
        data_frame=df_kpi,
        value_column="Actual",
        reference_column="Reference",
        title="KPI reference (reverse color)",
        reverse_color=True,
    ),
]

page = vm.Page(
    title="KPI cards",
    layout=vm.Flex(direction="row", wrap=True),  # (2)!
    components=[vm.Figure(figure=figure) for figure in example_cards + example_reference_cards],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
  1. For more information, refer to the API reference for kpi_card and kpi_card_reference.
  2. We use a Flex layout with direction=row and wrap=True to allow KPI cards to wrap to the next line when needed.

PyCafe logoRun and edit this code in PyCafe

# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
  - components:
      - figure:
          _target_: kpi_card
          data_frame: df_kpi
          value_column: Actual
          title: KPI with value
        type: figure
      - figure:
          _target_: kpi_card
          data_frame: df_kpi
          value_column: Actual
          title: KPI with aggregation
          agg_func: median
        type: figure
      - figure:
          _target_: kpi_card
          data_frame: df_kpi
          value_column: Actual
          title: KPI with formatting
          value_format: ${value:.2f}
        type: figure
      - figure:
          _target_: kpi_card
          data_frame: df_kpi
          value_column: Actual
          title: KPI with icon
          icon: Shopping Cart
        type: figure
      - figure:
          _target_: kpi_card_reference
          data_frame: df_kpi
          value_column: Actual
          reference_column: Reference
          title: KPI reference (pos)
        type: figure
      - figure:
          _target_: kpi_card_reference
          data_frame: df_kpi
          value_column: Actual
          reference_column: Reference
          agg_func: median
          title: KPI reference (neg)
        type: figure
      - figure:
          _target_: kpi_card_reference
          data_frame: df_kpi
          value_column: Actual
          reference_column: Reference
          title: KPI reference with formatting
          value_format: '{value:.2f}€'
          reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
        type: figure
      - figure:
          _target_: kpi_card_reference
          data_frame: df_kpi
          value_column: Actual
          reference_column: Reference
          title: KPI reference with icon
          icon: Shopping Cart
        type: figure
      - figure:
          _target_: kpi_card_reference
          data_frame: df_kpi
          value_column: Actual
          reference_column: Reference
          title: KPI reference (reverse color)
          reverse_color: true
        type: figure
    layout:
      direction: row
      wrap: true
      type: flex
    title: KPI cards

KPICards