Skip to content

Figure functions

Using figure functions in pure Dash app

Identical functions can also be used outside the Vizro framework in a pure Dash app by importing from the vizro.figures.library namespace: 

from vizro.figures.library import kpi_card, kpi_card_reference

vizro.figures

Built-in figure functions.

Usage documentation

How to use figures

kpi_card 

kpi_card(
    data_frame,
    value_column,
    *,
    value_format="{value}",
    agg_func="sum",
    title=None,
    icon=None
)

Creates a styled KPI (Key Performance Indicator) card displaying a value.

Warning

The format string provided to value_format is evaluated, so ensure that only trusted user input is provided to prevent potential security risks.

Parameters:

  • data_frame (DataFrame) –

    DataFrame containing the data.

  • value_column (str) –

    Column name of the value to be shown.

  • value_format (str, default: '{value}' ) –

    Format string to be applied to the value. It must be a valid Python format string where any of the below placeholders can be used.

    • value: value_column aggregated by agg_func.

    Common examples include:

    • "{value}": Displays the raw value.
    • "${value:0.2f}": Formats the value as a currency with two decimal places.
    • "{value:.0%}": Formats the value as a percentage without decimal places.
    • "{value:,}": Formats the value with comma as a thousands separator.
  • agg_func (str, default: 'sum' ) –

    String function name to be used for aggregating the data. Common options include "sum", "mean" or "median". More information on possible functions.

  • title (str | None, default: None ) –

    KPI title displayed on top of the card. If not provided, it defaults to the capitalized value_column.

  • icon (str | None, default: None ) –

    Name of the icon from the Google Material Icon Library to be displayed on the left side of the KPI title. If not provided, no icon is displayed.

Returns:

  • Card –

    A Dash Bootstrap Components card (dbc.Card) containing the formatted KPI value.

Example 
import vizro.models as vm
from vizro.figures import kpi_card

vm.Figure(figure=kpi_card(...))
Source code in src/vizro/figures/library.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def kpi_card(
    data_frame: pd.DataFrame,
    value_column: str,
    *,
    value_format: str = "{value}",
    agg_func: str = "sum",
    title: str | None = None,
    icon: str | None = None,
) -> dbc.Card:
    """Creates a styled KPI (Key Performance Indicator) card displaying a value.

    !!! warning
        The format string provided to `value_format` is evaluated, so ensure that only trusted
        user input is provided to prevent potential security risks.

    Args:
        data_frame: DataFrame containing the data.
        value_column: Column name of the value to be shown.
        value_format: Format string to be applied to the value. It must be a
            [valid Python format](https://docs.python.org/3/library/string.html#format-specification-mini-language)
            string where any of the below placeholders can be used.

            - value: `value_column` aggregated by `agg_func`.

            **Common examples include:**

             - `"{value}"`: Displays the raw value.
             - `"${value:0.2f}"`: Formats the value as a currency with two decimal places.
             - `"{value:.0%}"`: Formats the value as a percentage without decimal places.
             - `"{value:,}"`: Formats the value with comma as a thousands separator.

        agg_func: String function name to be used for aggregating the data. Common options include
            `"sum"`, `"mean"` or `"median"`. [More information on possible
            functions](https://stackoverflow.com/q/65877567).
        title: KPI title displayed on top of the card. If not provided, it defaults to the capitalized
            `value_column`.
        icon: Name of the icon from the [Google Material Icon Library](https://fonts.google.com/icons)
            to be displayed on the left side of the KPI title. If not provided, no icon is displayed.

    Returns:
         A Dash Bootstrap Components card (`dbc.Card`) containing the formatted KPI value.

    Example:
        ```python
        import vizro.models as vm
        from vizro.figures import kpi_card

        vm.Figure(figure=kpi_card(...))
        ```
    """
    title = title or f"{agg_func} {value_column}".title()
    value = data_frame[value_column].agg(agg_func)

    header = dbc.CardHeader(
        [
            html.P(validate_icon(icon), className="material-symbols-outlined") if icon else None,
            html.H4(title, className="card-kpi-title"),
        ]
    )
    body = dbc.CardBody(value_format.format(value=value))
    return dbc.Card([header, body], class_name="card-kpi")

kpi_card_reference 

kpi_card_reference(
    data_frame,
    value_column,
    reference_column,
    *,
    value_format="{value}",
    reference_format="{delta_relative:+.1%} vs. reference ({reference})",
    agg_func="sum",
    title=None,
    icon=None,
    reverse_color=False
)

Creates a styled KPI (Key Performance Indicator) card displaying a value in comparison to a reference value.

Warning

The format string provided to value_format and reference_format is evaluated, so ensure that only trusted user input is provided to prevent potential security risks.

Parameters:

  • data_frame (DataFrame) –

    DataFrame containing the data.

  • value_column (str) –

    Column name of the value to be shown.

  • reference_column (str) –

    Column name of the reference value for comparison.

  • value_format (str, default: '{value}' ) –

    Format string to be applied to the value. It must be a valid Python format string where any of the below placeholders can be used.

    • value: value_column aggregated by agg_func.
    • reference: reference_column aggregated by agg_func.
    • delta: Difference between value and reference.
    • delta_relative: Relative difference between value and reference.

    Common examples include:

    • "{value}": Displays the raw value.
    • "${value:0.2f}": Formats the value as a currency with two decimal places.
    • "{value:.0%}": Formats the value as a percentage without decimal places.
    • "{value:,}": Formats the value with comma as a thousands separator.
  • reference_format (str, default: '{delta_relative:+.1%} vs. reference ({reference})' ) –

    Format string to be applied to the reference. For more details on possible placeholders, see docstring on value_format.

  • agg_func (str, default: 'sum' ) –

    String function name to be used for aggregating the data. Common options include "sum", "mean" or "median". More information on possible functions.

  • title (str | None, default: None ) –

    KPI title displayed on top of the card. If not provided, it defaults to the capitalized value_column.

  • icon (str | None, default: None ) –

    Name of the icon from the Google Material Icon Library to be displayed on the left side of the KPI title. If not provided, no icon is displayed.

  • reverse_color (bool, default: False ) –

    If False, a positive delta will be colored positively (e.g., blue) and a negative delta negatively (e.g., red). If True, the colors will be inverted: a positive delta will be colored negatively (e.g., red) and a negative delta positively (e.g., blue).

Returns:

  • Card –

    A Dash Bootstrap Components card (dbc.Card) containing the formatted KPI value and reference.

Example 
import vizro.models as vm
from vizro.figures import kpi_card_reference

vm.Figure(figure=kpi_card_reference(...))
Source code in src/vizro/figures/library.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def kpi_card_reference(  # noqa: PLR0913
    data_frame: pd.DataFrame,
    value_column: str,
    reference_column: str,
    *,
    value_format: str = "{value}",
    reference_format: str = "{delta_relative:+.1%} vs. reference ({reference})",
    agg_func: str = "sum",
    title: str | None = None,
    icon: str | None = None,
    reverse_color: bool = False,
) -> dbc.Card:
    """Creates a styled KPI (Key Performance Indicator) card displaying a value in comparison to a reference value.

    !!! warning
        The format string provided to `value_format` and `reference_format` is evaluated, so ensure that
        only trusted user input is provided to prevent potential security risks.

    Args:
        data_frame: DataFrame containing the data.
        value_column: Column name of the value to be shown.
        reference_column: Column name of the reference value for comparison.
        value_format: Format string to be applied to the value. It must be a
            [valid Python format](https://docs.python.org/3/library/string.html#format-specification-mini-language)
            string where any of the below placeholders can be used.

            - value: `value_column` aggregated by `agg_func`.
            - reference: `reference_column` aggregated by `agg_func`.
            - delta: Difference between `value` and `reference`.
            - delta_relative: Relative difference between `value` and `reference`.

            **Common examples include:**

             - `"{value}"`: Displays the raw value.
             - `"${value:0.2f}"`: Formats the value as a currency with two decimal places.
             - `"{value:.0%}"`: Formats the value as a percentage without decimal places.
             - `"{value:,}"`: Formats the value with comma as a thousands separator.

        reference_format: Format string to be applied to the reference. For more details on possible placeholders,
            see docstring on `value_format`.
        agg_func: String function name to be used for aggregating the data. Common options include
            `"sum"`, `"mean"` or `"median"`. [More information on possible
            functions](https://stackoverflow.com/q/65877567).
        title: KPI title displayed on top of the card. If not provided, it defaults to the capitalized
            `value_column`.
        icon: Name of the icon from the [Google Material Icon Library](https://fonts.google.com/icons)
            to be displayed on the left side of the KPI title. If not provided, no icon is displayed.
        reverse_color: If `False`, a positive delta will be colored positively (e.g., blue) and a negative delta
            negatively (e.g., red). If `True`, the colors will be inverted: a positive delta will be colored
            negatively (e.g., red) and a negative delta positively (e.g., blue).

    Returns:
        A Dash Bootstrap Components card (`dbc.Card`) containing the formatted KPI value and reference.

    Example:
        ```python
        import vizro.models as vm
        from vizro.figures import kpi_card_reference

        vm.Figure(figure=kpi_card_reference(...))
        ```
    """
    title = title or f"{agg_func} {value_column}".title()
    value, reference = data_frame[[value_column, reference_column]].agg(agg_func)
    delta = value - reference
    delta_relative = delta / reference if reference else np.nan
    pos_color, neg_color = ("color-neg", "color-pos") if reverse_color else ("color-pos", "color-neg")
    footer_class = pos_color if delta > 0 else neg_color if delta < 0 else ""

    header = dbc.CardHeader(
        [
            html.P(validate_icon(icon), className="material-symbols-outlined") if icon else None,
            html.H4(title, className="card-kpi-title"),
        ]
    )
    body = dbc.CardBody(
        value_format.format(value=value, reference=reference, delta=delta, delta_relative=delta_relative)
    )
    footer = dbc.CardFooter(
        [
            html.Span(
                "arrow_circle_up" if delta > 0 else "arrow_circle_down" if delta < 0 else "arrow_circle_right",
                className="material-symbols-outlined",
            ),
            html.Span(
                reference_format.format(value=value, reference=reference, delta=delta, delta_relative=delta_relative)
            ),
        ],
        class_name=footer_class,
    )
    return dbc.Card([header, body, footer], class_name="card-kpi")