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.
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.
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.
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.
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.
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.
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.
Loading
The SingleValue component is able to show the default loading indicator
setting the loading prop to true.
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.
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.
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
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
Dynamic Range Stroke Only and Static Ranges
Point and Range with Area Variant
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
If label and value are empty the trend direction icon will be hidden.
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.
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.
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.).
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.
Putting it all together
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.
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.
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.
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.
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.
Grid - putting it all together
Let's have a look at the grid with all the accessors and props in action.