metric

A control that provides a visualization for a specific metric.

A metric must be a numerical value. The value is represented in the metric control on a linear or a circular gauge.
The control can also display a delta value, which is meant to give a hint about how the metric value is evolving.

Properties

Name	Type	Default	Description
value(★)	Union[int,float] dynamic		The value to represent.
type	str	"circular"	The type of the gauge. Possible values are: "none" "circular" "linear" Setting this value to "none" remove the gauge.
min	Union[int,float]	0	The minimum value of this metric control's gauge.
max	Union[int,float]	100	The maximum value of this metric control's gauge.
delta	Union[int,float] dynamic		The delta value to display.
delta_color	str		The color that is used to display the value of the delta property. If negative_delta_color is set, then this property applies for positive values of delta only. If this property is set to "invert", then values for delta are represented with the color used for negative values if delta is positive and delta is represented with the color used for positive values if it is negative.
title	str	None	The title of the metric.
negative_delta_color	str		If set, this represents the color to be used when the value of delta is negative (or positive if delta_color is set to "invert").
threshold	Union[int,float] dynamic		The threshold value to display.
show_value	bool	True	If set to False, the value is not displayed.
format	str		The format to use when displaying the value. This uses the printf syntax.
delta_format	str		The format to use when displaying the delta value. This uses the printf syntax.
bar_color	str		The color of the bar in the gauge.
color_map	dict		Indicates what colors should be used for different ranges of the metric. The color_map's keys represent the lower bound of each range, which is a number, while the values represent the color for that range. If the value associated with a key is set to None, the corresponding range is not assigned any color.
width	Union[str,number]	"20vw"	The width of the metric control, in CSS units
height	Union[str,number]	"20vh"	The height of the metric control, in CSS units
layout	dict[str, Any] dynamic		The plotly.js compatible layout object.
template	dict		The Plotly layout template.
template[dark]	dict		The Plotly layout template applied over the base template when theme is dark.
template[light]	dict		The Plotly layout template applied over the base template when theme is not dark.
id	str		The identifier that is assigned to the rendered HTML component.
properties	dict[str, Any]		Bound to a dictionary that contains additional properties for this element.
class_name	str dynamic		The list of CSS class names that are associated with the generated HTML Element. These class names are added to the default taipy-metric class name.
hover_text	str dynamic		The information that is displayed when the user hovers over this element.

^(★)value is the default property for this visual element.

Details

The metric control provides a graphical representation of a value in a quantitative context.
This value can result from a significant computational step or a KPI (Key Performance Indicator) in an industrial context.
In Taipy GUI, this control is implemented using Plotly's gauge charts.

The purpose of the control is to help evaluate a numerical value by graphically representing the value in a context using a gauge.
A quick look at the control immediately gives relevant information, yet the control still shows precise figures that a user can investigate further.

In addition to the main value, the metric control also lets you complement the graphs with a delta value that is meant to express the variation of the main value.

The control provides ways to customize the underlying gauge by setting its global range or the colors for sections of that range.

Usage

Simple case

See the entire code for this example

The most common use case for the metric control is displaying a value on a gauge, with a delta value indicating how much the value has increased or decreased compared to a previous state.
The value property (the default property for this control) holds the value to be represented. You can set the delta property to the value variation.
You can also add an indicator of a specific value, such as a threshold value, by setting the threshold property to the value of that parameter.

Say you have declared the following variables:

value = 72
delta = 15
threshold = 60

The following definition of the control:

Definition

MarkdownHTMLPython

<|{value}|metric|delta={delta}|threshold={threshold}|>

<taipy:metric delta="{delta}" threshold="{threshold}">{value}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{value}", delta="{delta}", threshold="{threshold}")

Renders as such:

Simple case

Setting the gauge type

See the entire code for this example

You can change the representation to a horizontal bar by setting the type property to "linear".

Here is the definition of a metric control that is horizontal:

Definition

MarkdownHTMLPython

<|{value}|metric|delta={delta}|threshold={threshold}|type=linear|>

<taipy:metric delta="{delta}" threshold="{threshold}" type="linear">{value}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{value}", delta="{delta}", threshold="{threshold}", type="linear")

Compared to the previous example, we only specified the type parameter.

Here is what this control will look like:

Horizontal gauge

Setting the gauge range

See the entire code for this example

You may need to specify the range represented in the gauge.

To achieve that, you simply need to set the min and max properties to the appropriate values.

Here is a definition of the metric control that specifies the control range:

Definition

MarkdownHTMLPython

<|{value}|metric|min=50|max=150|>

<taipy:metric min="50" max="150">{value}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{value}", min=50, max=150)

Here is how the control is represented:

Setting the control range

Hiding the value

See the entire code for this example

If you need only a rough representation of the value, you can hide the precise value itself by setting the show_value to False.

Here is a straightforward example of this:

Definition

MarkdownHTMLPython

<|90|metric|don't show_value|>

<taipy:metric show_value="false">90</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("90", show_value=False)

This definition produces the following output that anyone can interpret on the spot:

Hiding the value

Formatting the values

See the entire code for this example

The numerical value set to the properties value and delta can be displayed using a formatting string set to the respective properties format and delta_format.

Here is a speedometer example where the speed unit is relevant. We are using the value variation (delta) as a percentage.
The variables are defined as such:

speed = 60
variation = 15

We want to show the units for these two values: the speed expressed in kilometers per hour and its variation as a percentage.
Here is the control definition:

Definition

MarkdownHTMLPython

<|{speed}|metric|format=%d km/h|delta={variation}|delta_format=%d %%|>

<taipy:metric format="%d km/h" delta="{variation}" delta_format="%d %%">{speed}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{speed}", format="%d km/h", delta="{variation}", delta_format="%d %%")

The syntax for the format and delta_format properties is the one used by the native sprintf() function. In this case, values are both integers.
Note that in this example, we want the delta value to appear with a percent sign suffix. To get this result, you'll need to use the double percent symbol (%%) in the value for the delta_format property. In sprintf(), a single percent symbol is used for specifying format specifiers, so to actually print a literal percent sign, you need to escape it with another percent symbol.

Here is how the control displays:

Formatted values

Changing the indicator color

See the entire code for this example

By default, a positive value delta is rendered in green, indicating a good thing. Negative values are displayed in red, hinting at a bad thing.
In some situations, this is not the case: you then want to change the color used for the delta value using the delta_color property.

Measuring the concentration of CO2 gas in the atmosphere is such a situation: an increase in that value over time is concerning and would better be colored in red.
Here are the variables we want to represent:

co2_2014 = 396.37
co2_2024 = 421.13
delta = co2_2024-co2_2014

The control definition would be the following:

Definition

MarkdownHTMLPython

<|{co2_2024}|metric|delta={delta}|delta_color=invert|format=%.1f ppm|delta_format=%.1f ppm|min=300|max=500|>

<taipy:metric delta="{delta}" delta_color="invert" format="%.1f ppm" delta_format="%.1f ppm" min="300" max="500">{co2_2024}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{co2_2024}", delta="{delta}", delta_color="invert", format="%.1f ppm", delta_format="%.1f ppm", min=300, max=500)

In the range 300 to 500 ppm (parts per million, the unit used to measure the level of CO2), we represent the level of CO2 as of January 1st, 2024, and indicate how it evolved for the last ten years.
The variation is positive but must be shown in red.
We have set the delta_color property to "invert" to swap how positive and negative values for delta are interpreted, achieving the following image:

Changing the color of the variation indicator

Note that we could have set the precise colors for the value and delta value using the delta_color and negative_delta_color properties which are self-explanatory.
If delta_color is set to "invert" then positive values of delta are displayed using the color set to negative_delta_color, if there is one.

Customizing the gauge colors

See the entire code for this example

You can improve the interpretation of the metric control by coloring the gauge area with colors that provide information. The color_map property lets you do just that.

Here is an example where this is relevant: our metric control should display a color depending on its wavelength.
Here is the definition of the color map assigning color names to wavelength ranges:

color_wl = 530
color_map = {
    200: None,
    380: "violet",
    435: "blue",
    500: "cyan",
    520: "green",
    565: "yellow",
    590: "orange",
    625: "red",
    740: None,
}

color_wl represents the wavelength of the color we want to represent.

We can use the color map stored in color_map in the control definition:

Definition

MarkdownHTMLPython

<|{color_wl}|metric|color_map={color_map}|format=%d nm|min=200|max=800|bar_color=gray|>

<taipy:metric color_map="{color_map}" format="%d nm" min="200" max="800" bar_color="gray">{color_wl}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{color_wl}", color_map="{color_map}", format="%d nm", min="200", max="800", bar_color="gray")

Here is the result:

Changing the color of the variation indicator

You can immediately spot that the indicated wavelength is a green color.

Fine tuning the control

See the entire code for this example

The property layout can be set to a dictionary that acutely defines parameters that impact the control rendering.
The Plotly library defines the configuration of this dictionary. The complete documentation for that object can be found on this page from the Plotly documentation set.

Here is an example of a layout configuration:

value = 45
layout = {
    "paper_bgcolor": "lightblue",
    "font": {
        "size": 30,
        "color": "blue",
        "family": "Arial",
    },
}

We request that the control be displayed on a light blue background and that the font that displays the value be rather large and drawn in blue.

Let us use the dictionary layout in the control definition:

Definition

MarkdownHTMLPython

<|{value}|metric|layout={layout}|>

<taipy:metric layout="{layout}">{value}</taipy:metric>

import taipy.gui.builder as tgb
...
tgb.metric("{value}", layout="{layout}")

To obtain the following image:

Fine tuning the control parameters

Styling

All the metric controls are generated with the "taipy-metric" CSS class. You can use this class name to select the metric controls on your page and apply style.