SingleValue

The SingleValue is a simple and concise representation of a single data point or metric , which can either be a text or a number.

Import

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

Use cases

The SingleValue expects a single value as an input. This value needs to be passed to the visualisation's data prop as either a Number or String.

CodeSandbox

Change the size of the SingleValue

The SingleValue component will always use all of the available space that it is given. In order to control the size of the SingleValue, it has to be wrapped inside a container and the container set to your desired size.

CodeSandbox

Customizing and formatting units

When passing a number to the data attribute, you can use the formatter prop to change how the number is represented. All the Design System formatters together with their respective configurations are supported. The suffix provided by certain formatters will be overwritten by the unit prop if defined.

CodeSandbox

Change the color of the SingleValue

With the color prop the user can change the SingleValue's color to any Design System color token as well as any rgb, hex or CSS color. If no color is set, the default color is automatically set based on the current theme.

CodeSandbox

Add more context to a Single Value

In order to add additional context to a SingleValue, you can add any combination of the following props to the visualization:

• prefixIcon: This prop allows the user to set a prefixed symbol as a ReactNode, consisting of an icon, emoji, single character, glyph, or Design System icon. It will be displayed to the left of the value.
• unit: With this prop it is possible to set a custom unit to be displayed with the single value, which will be appended to the right of the value. This prop takes priority over units provided with the formatter prop.
• label: This prop enables the user to set a custom text which will be shown above the value.

CodeSandbox

Changing the color dynamically with thresholds

You can dynamically change the color of the SingleValue visualization based on any number of thresholds. If the value passed to the visualization is a string (text), thresholds can be set with either a 'equal-to' or 'not-equal-to' operator. On the other hand, if your value is a number you can utilize anyone of the following operators:

• 'greater-than'
• 'less-than'
• 'greater-than-or-equal-to'
• 'less-than-or-equal-to'
• 'equal-to'
• 'not-equal-to'

Note: When multiple thresholds are applicable (evaluate to true) the last valid threshold has priority.

CodeSandbox

Add additional context by visualizing a trend over time

In its most basic configuration a SingleValue displays exactly that, a single value. In most use cases, however, a numerical value changes over time. In order to add additional context to the value being displayed and its change over time an optional sparkline can be added to the SingleValue visualization.

Sparkline

In order to display a Sparkline within the SingleValue component you need to add the <Sparkline /> subcomponent to the SingleValue chart. The Sparkline component requires data of type Timeseries or Timeseries[] to be passed to the data prop. If more than one series is provided, the first one is used. The datapoints within the series need to provide a time dimension as well as a numerical value.

The Sparkline has two variants and can be either displayed as a line(default) or area.

You can further customise the Sparkline by setting its color prop to any of the Design System ColorPalette.

Lastly, x-axis ticks can be visualized on the Sparkline by using the showTicks prop. By default, these ticks are hidden.

CodeSandbox

Loading

The SingleValue component is able to show the default loading indicator setting the loading prop to true.

CodeSandbox

Empty State

By using the <EmptyState /> subcomponent it is possible to define a custom message that will be displayed if no data was provided to the SingleValue component.

CodeSandbox

Error State

The <ErrorState /> subcomponent can be used to customise the error message that will be displayed when an error occurs in the SingleValue component.

CodeSandbox

Thresholds on Sparkline

Thresholds are used to mark meaningful ranges or values on a Sparkline and they add contextual information to a numerical axis. There are two variants of thresholds:

• a specific point represented by a line across.
• a range - or filled area - represented by a band across.

Point and Range

CodeSandbox

Both point and range can be represented by static or dynamic data sources. A static data source has a single value representing a point or a single key-value pair representing a fixed range. A dynamic data source has a data array containing more than one value or various key-value pairs.

There are three different types of threshold markers:

• Range filled, where the value range is defined in order to display the threshold band. The upper and lower lines are not drawn.

• Range stroke-only variant, where a value range is defined in order to display the threshold band represented by upper and lower dashed lines.

• Point, where only one value is required to display the threshold. It's represented by a dashed line.

Dynamic Point and Dynamic Range

CodeSandbox

Dynamic Range Stroke Only and Static Ranges

CodeSandbox

Point and Range with Area Variant

CodeSandbox

Add detailed information about the trend

Another way to add detailed information about the SingleValue trend is to use a Trend component.

Trend

The Trend allows user to configure and display a current state of trend including trend direction icon, color, trend value, and label.

In order to display a Trend within the SingleValue component you need to add the <Trend /> subcomponent to the SingleValue component.

Trend anatomy

The Trend component consists of the following elements:

• icon
• value
• label

To set the trend direction the direction prop should be used. The direction prop accepts one of the following values: upward, downward, and neutral.

The showIcon prop is used to show or hide the trend direction icon. By default, the showIcon prop is set to true.

The value prop is used to set the trend value. The value prop accepts a numeric value.

The label prop is used to set the trend label.

CodeSandbox

Trend direction calculation based on value

When a value prop is provided without a direction prop, the trend direction is calculated based on the value prop's sign: positive value results in upward trend direction, negative value in downward trend, and zero value in neutral trend direction.

In case neither the direction nor value prop is provided, the trend direction is set to neutral.

CodeSandbox

Trend coloring and formatting options

The color for each direction of a trend can be customized using the colorOverrides prop. The colorOverrides prop accepts an object with the following optional keys: upward, downward, and neutral. Each key accepts a string representing a valid CSS color.

The formatter prop can be used to format the trend value including adding a unit (e.g. bytes, bits, etc.).

CodeSandbox

Inverse trend

An upward trend direction doesn't always represent a positive change, and the downtrend doesn't always represent a negative one. For example, when displaying a trend of a response time, a downward trend direction represents a positive change, while an upward trend in a host CPU usage represents a negative change.

To inverse a trend the inverseTrend prop should be used. Currently, the inverseTrend prop accepts two options: none and color. The none option doesn't affect the trend in any way and is a default behaviour. The color option inverts the default colors of the icon and the value (i.e. the icon and the value are colored as if the trend direction is opposite to the actual trend direction).

When colorOverrides are used, the inverseTrend prop with color option gets ignored.

CodeSandbox

Putting it all together

CodeSandbox

Render multiple SingleValues in a grid

In order to render multiple SingleValue components in a grid, you can use the SingleValueGrid component. SingleValue components in the grid will share the internal layout and styles to create a consistent look and feel. The component will occupy all the available space in the container it's located in and automatically render the SingleValue components.

The SingleValueGrid component expects an array of strings, numbers, or objects of a free shape.

CodeSandbox

Control over the grid elements using accessors

In order to have more granular control over the grid elements look, you can pass an array of objects to the SingleValueGrid component. Using Value, Trend, and Sparkline subcomponents with various accessors you can customize the grid elements. Accessor is a string that represents a name of a prop name (or nested prop name using a dot notation, e.g. trend.direction) in the data array object that should be used to override original prop of the SingleValue component and it's subcomponents.

Grid accessors and props

On the SingleValueGrid component, you can use the following accessors:

• colorAccessor - accessor to override a colors for individual grid elements.
• labelAccessor - accessor to override a label.
• prefixIconAccessor - accessor to override a prefix icon.

The SingleValueGrid also accepts a color prop to set a default color for all grid elements. When both color and colorAccessor props are provided, the grid element will try to access a color in the data object using the colorAccessor, and if it's not found, the color prop value will be applied. The same logic applies to most of the accessors.

On a grid level it's also possible to set value alignment using the alignment prop and thresholds using the thresholds prop.

CodeSandbox

Value accessors and props

On the Value subcomponent, you can use the following accessors:

• dataAccessor - accessor to get a value from data array object.
• formatterAccessor - accessor to retrieve the formatter options for the value.
• unitAccessor - accessor to retrieve the unit for the value.

The unit and formatter props can be used to set a default unit and formatter for all grid elements.

CodeSandbox

Trend accessors and props

On the Trend subcomponent, you can use the following accessors:

• directionAccessor - accessor to get a trend direction.
• valueAccessor - accessor to get a trend value.
• labelAccessor - accessor to get a trend value.
• formatterAccessor - accessor to get formatter for the trend value.
• inverseTrendAccessor - accessor to retrieve an inverse trend options.

CodeSandbox

Sparkline accessors and props

The Sparkline subcomponent extends the standard Sparkline component with two accessors:

• dataAccessor - accessor to get a data for the sparkline.
• colorAccessor - accessor to get a color of the sparkline.

CodeSandbox

Grid - putting it all together

Let's have a look at the grid with all the accessors and props in action.

CodeSandbox

Props

SingleValueProps

Name	Type	Default	Description
label?		-	Optional label text to show above the value.
prefixIcon?		-	Optional icon to show left of the value.
color?		'default'	State of the value. This affects text and prefix icon color.
unit?		-	Optional unit to show in the right of the value
data	|	-	Data to show within the chart.
formatter?	| <, >	-	If specified, value will be formatted with given formatter options.
thresholds?	[]	-	Threshold configurations defining conditions to match a given value.
alignment?		-	Horizontal alignment of icon, value and unit.
loading?		false	Show the loading indicator when truly.
className?		-	Class names to be attached to the outer container.
style?		-	Inline styles that will override the outer container.

SparklineProps

Name	Type	Default	Description
data	| []	-	Data to show
color?		-	Sparkline color
variant?		-	Sparkline variant (line, area)
showTicks?		-	Whether Sparkline shows X Axis ticks or not
loading?		-	When true: Sets an overlay with default loader.
gapPolicy?	|	-	Gap policy

SparklineThresholdProps

Name	Type	Default	Description
data		-	The threshold data to be graphed by the component
color		-	The unique color picked for this timeseries representation in HEX, RGB, Color Token or HSL.
strokeOnly?		-	Whereas to show the threshold ranges filled or only the strokes

TrendProps

Name	Type	Default	Description
direction?		-	The direction of a trend.
showIcon?		true	Flag to show the icon or not.
value?		-	The trend value
label?		-	The trend label
inverseTrend?		'none'	Inverts 'upward' and 'downward' color options.
colorsOverride?		-	Overrides colors of the trend icon and value for trend directions.
formatter?	| <, >	-	If specified, the value will be formatted with given formatter options.

SingleValueGridProps

Name	Type	Default	Description
data	( | | <, >)[]	-	The data source for the SingleValueGrid component.
color?		-	The default color for the SingleValues. This color will be overwritten by individual colors specified in the SingleValueGridData or thresholds prop.
colorAccessor?		-	Accessor function to override colors for individual SingleValue components.
thresholds?	[]	-	Threshold configurations that define conditions to match a given value. These configurations will overwrite the color prop for the corresponding SingleValue components.
labelAccessor?		-	Accessor function for individual labels of each SingleValue component.
prefixIconAccessor?		-	Accessor function for individual prefix icons of each SingleValue component.
alignment?		'start'	Horizontal alignment of icons, values, units, labels, and trends within each SingleValue component.

SingleValueGridValueProps

Name	Type	Default	Description
dataAccessor?		-	Accessor function to retrieve the data for the value.
formatter?	| <, >	-	Formatter options for formatting the value.
formatterAccessor?		-	Accessor function to retrieve the formatter options for the value.
unit?		-	Unit for the value.
unitAccessor?		-	Accessor function to retrieve the unit for the value.

SingleValueGridSparklineProps

extends

Name	Type	Default	Description
dataAccessor?		-	Accessor function or string to retrieve the data for the sparkline.
colorAccessor?		-	Accessor function to retrieve the color of the sparkline.

SingleValueGridTrendProps

Name	Type	Default	Description
directionAccessor?		-	Accessor to retrieve the trend direction.
valueAccessor?		-	Accessor to retrieve the trend value.
labelAccessor?		-	Accessor to retrieve the trend label.
showIcon?		true	Determines whether to show the trend icon.
colorsOverride?		-	Overrides the colors of the trend icon and value for different trend directions.
formatter?	| <, >	-	Formatter options or function to format the trend value.
formatterAccessor?		-	Accessor to retrieve the formatter options for the trend value.
inverseTrend?		'none'	Inverts 'upward' and 'downward' color options.
inverseTrendAccessor?		-	Accessor to retrieve the inverse trend options.

SingleValue.Sparkline

SingleValue.Sparkline provides a subcomponent where the Sparkline component can be added.

SingleValueSparklineProps

Signature:

export declare type SingleValue = <<, >>;

SingleValue.Trend

SingleValue.Trend provides a subcomponent where the Trend component can be added.

TrendProps

Name	Type	Default	Description
direction?		-	The direction of a trend.
showIcon?		true	Flag to show the icon or not.
value?		-	The trend value
label?		-	The trend label
inverseTrend?		'none'	Inverts 'upward' and 'downward' color options.
colorsOverride?		-	Overrides colors of the trend icon and value for trend directions.
formatter?	| <, >	-	If specified, the value will be formatted with given formatter options.

SingleValue.EmptyState

SingleValue.EmptyState provides a subcomponent where the Empty state wrapper can be set.

EmptyStateProp

Name	Type	Default	Description
children	.	-

SingleValue.ErrorState

SingleValue.ErrorState provides a subcomponent where the Error state wrapper can be set.

ErrorStateProps

Name	Type	Default	Description
children	. | ((errorMessage: ) => .)	-