GaugeChart

A Gauge Chart is a circular chart that displays information on a numeric scale. It's great for showing performance metrics or progress towards a goal.

OverviewProperties

Import

import { GaugeChart } from '@dynatrace/strato-components/charts';

Use cases

The GaugeChart expects a numerical value as an input. This value needs to be passed to the visualization's value prop as a Number.

You can also provide custom min and max props to set the scale of the GaugeChart, and if none are provided, the default min will be 0 and max will be 100.

Learn more about the data format here.

CodeSandbox

Object values

The GaugeChart accepts object values in addition to numeric values. When passing an object value, a valueAccessor prop needs to be specified to indicate which field should be used as the gauge's display value.

CodeSandbox

In the example above, the gauge displays the value from the value field, while ColorRules evaluate against other fields using their own valueAccessor prop. When multiple rules match, the first matching rule takes precedence.

Change the chart color/s

The GaugeChart provides several ways to customize the appearance of your gauge:

1. Direct Color Assignment: Set a single color for the entire gauge arc.
2. Color Rules: Apply conditional coloring based on the gauge's value.

Direct Color Assignment

The GaugeChart allows the user to customize an arc with a custom color. It accepts a color prop that can be set to any valid color string that utilizes a format supported by web browsers, including RGB, HSL and HEX.

CodeSandbox

Using Color Rules

For more advanced coloring scenarios, you can use the ColorRule component to apply conditional coloring based on the gauge's value. This is particularly useful for creating visual indicators for different value ranges.

CodeSandbox

Color rules can be applied based on the gauge's value using different comparators:

• 'greater-than'
• 'less-than'
• 'greater-or-equal'
• 'less-or-equal'
• 'equals'

In the example above, we demonstrate several ways to use color rules:

1. Basic color rules: Changing colors based on value thresholds
2. With default color: Shows how rules override the default color
3. Multiple rules: Demonstrates how multiple rules work together

When multiple rules match, the most specific rule (highest matchValue for 'greater' comparators, lowest for 'less' comparators) will take precedence.

You can combine color rules with threshold indicators to create clear visual cues for different value ranges in your gauge charts.

For more details about available comparators and options, see the Color Rules section.

Customize chart information

There are some subcomponents that can be used on the GaugeChart to display more information about the chart: <GaugeChart.Label> and <GaugeChart.ThresholdIndicator>.There are three ways to configure the <GaugeChart.Label> slot:

1. No slot is defined: The component does not display any labels.
2. Slot is defined without a child component: The component automatically generates default labels using the min, max, and value props, applying the specified formatter prop for consistent formatting.
3. Slot is defined with a child component: The provided child component is used directly as the label, and no automatic formatting is applied.

CodeSandbox

Add more context to a GaugeChart

To provide additional context in a GaugeChart, you can enhance it with icons or emojis using the prefixIcon prop. This prop accepts a ReactNode, allowing you to display a symbol—such as an icon, emoji, single character, glyph, or a Design System icon—before the value. The symbol will appear to the left of the chart’s value.

CodeSandbox

Sizing

Different sizes can be set on the GaugeChart to display the information. By default, the chart will use all the available container size up to a maximum height of 300 pixels. This maximum height can be changed by providing a value in the height prop of the GaugeChart. If a number is passed to this prop without any unit specified, it will be treated as px. You can also specify the width prop, and it works in the same way.

Resizing the chart will especially affect the label. If a string is provided to the label slot, both the arc and the strings will grow accordingly. However, size will not be affected if another type of element is provided as label, but size can be modified manually. The arc will resize either way.

CodeSandbox

Thresholds

Thresholds are used to mark meaningful values on a GaugeChart. In order to set one or multiple thresholds, you can use the <GaugeChart.ThresholdIndicator> slot. These Thresholds have a value prop to define them. You can also optionally display the threshold indicator via the showIndicator prop and customize their color by using the prop color.

CodeSandbox

Add tooltip

The GaugeChart has an optional Tooltip to display additional information and will be shown when the user hovers over the segment. Use the subcomponent <GaugeChart.Tooltip> to enable it.

CodeSandbox

Series actions

A series action is a creator-defined interaction with a given data point in the chart. Basic interactions include copying a series name and inspecting the underlying data of a data point. Series actions support both synchronous and asynchronous templates. In order to enable chart interactions, the ChartSeriesAction subcomponent needs to be appended within the GaugeChart. More subcomponents can be added within this component, for instance ChartSeriesAction.Item, where you can provide a custom action that will appear in the legend menu. That action can execute any custom logic in its onSelect callback or get disabled via a disabled prop. Intents could be added as part of the series action as well with ChartSeriesAction.Intent.

CodeSandbox

Intent options

The GaugeChart supports intent options in the toolbar. The intents appear in the toolbar's dropdown menu, allowing users to perform actions such as sharing a chart or viewing data in another application.

To add intent options to a GaugeChart, use the GaugeChart.Intent subcomponent:

Intent properties

• payload: An object containing the data to be passed to the target app. The structure depends on the target application's requirements.
• options: Configuration options for the intent.
• keyProperties: Array of properties that should be included as keys in the intent.
• recommendedAppId: Suggested target application ID.
• recommendedIntentId: Suggested intent ID.
• responseProperties: Array of properties to be included in the response.
• icon: Optional custom icon to be displayed next to the intent option.
• onResponse: Optional callback function that is called when a response is received from the target app.

Formatter

The GaugeChart has a formatter prop that accepts any function to provide format to the relevant chart values. One of the uses of this formatter can be to attach a custom unit or string to the value. The default formatter shows the value without any format.

Additionally, there is a custom formatter option available that allows you to change the input unit to one of your choice, e.g.: if the input unit is bits, you are able to switch and display the unit as bytes, correctly formatted. The formatted value will appear in the chart tooltip. The use cases below outline each of these scenarios.

CodeSandbox

Styling

The GaugeChart also accepts custom styling, which could be set using the props className and/or style, as a regular html element.

CodeSandbox