Skip to content

Figure functions

API reference for all built-in CapturedCallable figure functions to be used in the Figure. The how-to guide on figures contains more information.

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

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: Note that the format string provided to value_format is being 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. Defaults to "{value}".

    • 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". Default is "sum". For more information on possible functions, see https://stackoverflow.com/questions/65877567/passing-function-names-as-strings-to-pandas-groupby-aggregrate.

  • title (Optional[str], default: None ) –

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

  • icon (Optional[str], 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.

Examples:

Wrap inside vm.Figure to use as a component inside vm.Page or vm.Container.

>>> import vizro.models as vm
>>> from vizro.figures import kpi_card
>>> vm.Page(title="Page", components=[vm.Figure(figure=kpi_card(...))])
Source code in src/vizro/figures/_kpi_cards.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
@capture("figure")
def kpi_card(
    data_frame: pd.DataFrame,
    value_column: str,
    *,
    value_format: str = "{value}",
    agg_func: str = "sum",
    title: Optional[str] = None,
    icon: Optional[str] = None,
) -> dbc.Card:
    """Creates a styled KPI (Key Performance Indicator) card displaying a value.

    **Warning:** Note that the format string provided to `value_format` is being evaluated, so ensure that only trusted
    user input is provided to prevent
    [potential security risks](https://stackoverflow.com/questions/76783239/is-it-safe-to-use-python-str-format-method-with-user-submitted-templates-in-serv).

    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. Defaults to "{value}".

            - 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". Default is "sum". For more information on possible functions, see
            https://stackoverflow.com/questions/65877567/passing-function-names-as-strings-to-pandas-groupby-aggregrate.
        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.

    Examples:
        Wrap inside `vm.Figure` to use as a component inside `vm.Page` or `vm.Container`.
        >>> import vizro.models as vm
        >>> from vizro.figures import kpi_card
        >>> vm.Page(title="Page", components=[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(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: Note that the format string provided to value_format and reference_format is being 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. Defaults to "{value}".

    • 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. Defaults to "{delta_relative:+.1%} vs. reference ({reference})".

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

    String function name to be used for aggregating the data. Common options include "sum", "mean" or "median". Default is "sum". For more information on possible functions, see https://stackoverflow.com/questions/65877567/passing-function-names-as-strings-to-pandas-groupby-aggregrate.

  • title (Optional[str], default: None ) –

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

  • icon (Optional[str], 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). Defaults to False.

Returns:

  • Card –

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

Examples:

Wrap inside vm.Figure to use as a component inside vm.Page or vm.Container.

>>> import vizro.models as vm
>>> from vizro.figures import kpi_card_reference
>>> vm.Page(title="Page", components=[vm.Figure(figure=kpi_card_reference(...))])
Source code in src/vizro/figures/_kpi_cards.py 
 75
 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
@capture("figure")
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: Optional[str] = None,
    icon: Optional[str] = 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:** Note that the format string provided to `value_format` and `reference_format` is being evaluated,
    so ensure that only trusted user input is provided to prevent
    [potential security risks](https://stackoverflow.com/questions/76783239/is-it-safe-to-use-python-str-format-method-with-user-submitted-templates-in-serv).

    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. Defaults to "{value}".

            - 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`. Defaults to "{delta_relative:+.1%} vs. reference ({reference})".
        agg_func: String function name to be used for aggregating the data. Common options include
            "sum", "mean" or "median". Default is "sum". For more information on possible functions, see
            https://stackoverflow.com/questions/65877567/passing-function-names-as-strings-to-pandas-groupby-aggregrate.
        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). Defaults to `False`.



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

    Examples:
        Wrap inside `vm.Figure` to use as a component inside `vm.Page` or `vm.Container`.
        >>> import vizro.models as vm
        >>> from vizro.figures import kpi_card_reference
        >>> vm.Page(title="Page", components=[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(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")