HistogramChart

Import

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

Use cases

The HistogramChart expects an array of bins where each bin represents a continuous range of values. A bin is defined by two key parameters: the range (from and to), which determines its width, and the count or frequency (value), which determines its height.

CodeSandbox

Uneven Bin Widths

The HistogramChart accommodates uneven bin widths, providing a clearer representation of the data. Each bin corresponds to a specific range of values and these ranges can vary from one bin to another.

CodeSandbox

Overlapped and Stacked Bins

In some instances of the HistogramChart, when bins are not perfectly aligned along the x-axis, the resulting bars may overlap. Conversely, if a bar aligns perfectly, it will be stacked.

CodeSandbox

CodeSandbox

Size

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 HistogramChart. If a number is passed to this prop without any unit specified, it will be treated as px.

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. In order to enable chart interactions, the ChartSeriesAction subcomponent needs to be appended within the HistogramChart. More subcomponents can be added within this component, for instance the ChartSeriesAction.Item, where custom logic can be applied.

CodeSandbox

Legend

The purpose of the legend is to provide additional identifying information for the chart, without needing to interact with the legend directly.

Visibility

The legend of the HistogramChart is shown by default. In order to hide or show the legend, you need to set the value of legend.hidden on the subcomponent.

Position

By default, the position of the legend of the HistogramChart is set automatically. This option prioritizes the legend placement to the right of the chart area. When the chart width is reduced, the legend is repositioned to the area beneath the chart. It is also possible to explicitly set the chart's legend position to right or bottom with the position prop.

Legend ratio

By default, the legend occupies 25% of the container width, in the case where the legend is positioned on the right and 25% of the container height if the legend position is on the bottom.

It is possible to override the default legend ratio by setting a custom percentage value for the ratio prop. The expected value is in the range of 5-80. Values out of expected ranges will roll back to the default legend ratio.

CodeSandbox

Chart interactions

Chart interactions enable additional possibilities for end users to interact with the data plotted within the chart area. The interactive options currently supported within the HistogramChart are zoom-x, zoom in, zoom out, and pan. To incorporate these interactions, the ChartInteractions subcomponent must be added to the HistogramChart. The chart interaction can then either be triggered using keyboard shortcuts or by the optional chart toolbar. To enable the toolbar with the chart interactions, the ChartToolbar subcomponent must be added to the HistogramChart. To set initial position of the toolbar, the placement prop can be used.

Explore

The explore functionality is the default mode and it allows you to inspect the data within the chart. It includes an optional feature to select an area to zoom along the x-axis. In order to enable this option it is necessary to add the ChartInteractions.ZoomX subcomponent to the ChartInteractions component. You can also pan with the mouse middle button in Explore mode by enabling the ChartInteractions.Pan subcomponent.

You can optionally trigger this mode from the keyboard by pressing E while the chart has focus.

Zoom-In and Zoom-Out

The zoom functionality within the HistogramChart allows users to zoom in to the chart's plotted data by a fixed point along the x-axis. The chart supports zoom in (incremental) and zoom out (decremental) actions.

In order to enable either of these zoom options on a chart it is necessary to add the ChartInteractions.Zoom subcomponent to the ChartInteractions component.

You can optionally zoom in/out different ways by first focusing the chart:

• Pressing Cmd (Mac) or Ctrl (Windows) + the mouse wheel, will generate a zoom in/out trigger.
• Pressing Cmd (Mac) or Ctrl (Windows) + ↑ (Up Arrow) will zoom-in.
• Pressing Cmd (Mac) or Ctrl (Windows) + ↓ (Down Arrow) will zoom-out.

Pan

Once a user has zoomed into the plotted data on a chart, panning can optionally be enabled. Panning allows users to navigate left and right along the x-axis whilst in a zoomed-in state. In order to enable this functionality, the ChartInteractions.Pan subcomponent needs to be added to the ChartInteractions component.

You can optionally trigger this mode from the keyboard by pressing P while the chart has focus.

Once you have triggered this mode:

• Pressing ← (Left Arrow) will pan to the left. You can also press Shift to increase the speed of pan movement.
• Pressing → (Right Arrow) will pan to the right. You can also press Shift to increase the speed of pan movement.

Reset

Reset will restore the chart to its initial state.

You can optionally trigger this action from the keyboard by pressing R while the chart has focus.

• Double clicking on any part of the chart will trigger a reset.

CodeSandbox

Axes

To configure the axes of the HistogramChart, the HistogramChart.XAxis and HistogramChart.YAxis subcomponents can be added. The label property sets the axis label. Axis scale boundaries can be set with the min and max props. Both XAxis and YAxis supports linear and log scales.

CodeSandbox

Both HistogramChart.XAxis and HistogramChart.YAxis subcomponents also support data-max in the max property and data-min in the min property. These special values allow for granular control over the Y-axis scale boundaries. By default, the auto value is used for both min and max properties. The auto mode automatically determines both the minimum and maximum values of the Y-axis scale based on the data in the chart (similar to data-min and data-max) and sets the Y-axis baseline to zero.

Multiple Y-axes

The HistogramChart supports multiple Y-axes. HistogramChart.YAxis provides a position property which can be set to either left or right.

When you specify multiple Y-axes, the chart automatically assigns data series to Y-axes based on the unique units of the data. The first unique unit is assigned to the left Y-axis, and the second unique unit to the right Y-axis. Note that any additional data series with different units from those already used will not be displayed.

Currently, it's not possible to assign data series to specific Y-axes, nor is it possible to use the same unit for both Y-axes.

CodeSandbox

Tooltip

Tooltips are used to display additional detailed information about a selected data point and can be enabled by adding the HistogramChart.Tooltip subcomponent. The tooltip variant defines whether the tooltip should contain data points from all bins (shared) for the selected bin, or just the closest one (single). The seriesDisplayMode prop can be used to define whether the tooltip should be comprised of a single line of information or multiple lines.

The sequence of the input data in the chart determines the arrangement of the tooltip series.

Single

CodeSandbox

Shared

CodeSandbox

Formatter

The unit for the HistogramChart, by default, will be appended to the specified value. There are two other options in the formatter that allow for greater customization. The first option enables you to prepend the unit to the value, while the second option enables you to ignore the original unit and append a custom string instead. Additionally, there is a custom formatter option available to allow 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 is applied in the axis ticks, as well as in the tooltip and the axis magnifier. The use cases below outline each of these scenarios.

The precision of the formatter will adapt automatically based on the data decimals if there is no precision configuration from the custom formatter option.

CodeSandbox

Annotations

Annotations are used to visualize specific events or contextual notes on the HistogramChart in the form of markers placed in the bins position.

The marker represents an annotation at a certain bin. They can be either a value (a certain number) or a range (from-to object), depending on the data provided to the Annotation. Annotations within the same bin are grouped together under a single marker that displays the number of grouped annotations. Markers can be displayed on a single or multiple tracks. When there are more than three tracks, an overflow scroll is applied.

Add annotations to the chart

In order to visualize annotation data inside the HistogramChart, a HistogramChart.Annotations component should be initialized. This component should have at least one track, that contains a marker component per annotation data point.

An annotation data point should contain the from-to bin information (value: {from: number, to:number}) or a certain point (value: number), a required title that would fill the marker content, and the optional description, which will be displayed in the tooltip.

CodeSandbox

Visual customization

Tracks and markers support visual customization in order to differentiate various types of annotations.

It's possible to set custom colors on both the track (to be applied to all markers) and the marker level by using the color property on the respective component. A marker's custom color has precedence over track's. This color can be set to any Design System color token, as well as any rgb, hex or CSS color.

The symbol property allows you to apply an icon, emoji, single letter, glyph, or Design System icon to either an individual marker or to an entire track. When applied to a track, this symbol will be used as the default.

When markers partially overlap one another, the order of the annotations defines which marker is displayed on top. Value annotations are always displayed above Range-based ones. It's also possible to customize the marker display order, by using the priority property. The higher the value of the priority property, the higher precedence the marker has. The priority property also affects the color of markers i.e. within a group, the color of the marker with the highest priority will be applied to the group.

It's possible to assign a label to a track using the label property. Be aware that labels are hidden by default. To show a track's label, the showLabels property has to be applied to the HistogramChart.Annotations component.

CodeSandbox

Visibility

An entire track can be hidden by adding the hidden property to the HistogramAnnotations.Track component. The same configuration can be applied to a marker, by setting the hidden property on the HistogramAnnotations.Marker component.

When hovering a marker (with the cursor), an annotation indicator appears over the chart area. The indicator's visibility can be customized on either a track or marker level by using the indicatorsDisplay property:

• With the auto option, the default behaviour is applied - indicators appear on hover.
• The always option sets indicators to always be visible within the chart area, regardless of the hovering behavior.
• The never option sets indicators to never be visible.

CodeSandbox

Thresholds

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

• a specific point represented on the Y-axis and a line across.
• a range - or filled area - represented by a pill on the Y-axis and 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 unless the pill is hovered.

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

• Point, where only one value is required to display the threshold. It's represented by a dashed line and when the point is hovered the line becomes a continuous line.

Dynamic Point

CodeSandbox

Dynamic Range

CodeSandbox

Dynamic Range Stroke Only

CodeSandbox

There is no limit defined for the number of threshold ranges or points that can be used in a single HistogramChart.

By default, thresholds are positioned on the left axis and with the use of the position prop, we can place thresholds on the right axis or on both, as depicted below.

Left Axis

CodeSandbox

Right Axis

CodeSandbox

Dual Axis

CodeSandbox

Error state

The ErrorState subcomponent is responsible for handling errors in a graceful manner, ultimately improving the overall user experience. Its primary function is to catch any errors that may occur with the data and display a fallback UI instead of crashing the entire application. The fallback UI occupies the full width and height of the chart, ensuring that users are still provided with a meaningful interface even in the presence of errors.

CodeSandbox

The ErrorState subcomponent offers a versatile feature that enables it to handle both default and custom error messages. You can provide a custom message through the ErrorState subcomponent, which will then override the default error message. This flexibility allows developers to tailor error messages to their specific needs and requirements, ensuring a more personalized and informative user experience.

CodeSandbox

The ErrorState subcomponent provides the flexibility to format custom error messages using HTML, which allows for enhanced customization and adaptability in presenting error information. Furthermore, it is possible to incorporate the original thrown error within your custom error message, ensuring that users receive comprehensive and relevant information when an error occurs.

CodeSandbox

CodeSandbox

EmptyState

The EmptyState subcomponent serves as a fallback when there is no data available to display in a chart. Its purpose is to provide a user-friendly way of informing the user about the current situation. When there is no data, a fallback UI is displayed occupying the full width and height of the chart, along with a default message.

CodeSandbox

A feature of EmptyState is its ability to handle custom messages. It provides the flexibility to format custom messages using HTML, which allows for enhanced customization and adaptability in presenting error information.

CodeSandbox

CodeSandbox

Loading

The loading prop is a boolean value that can be passed to the HistogramChart component to control its loading state. When the loading prop is set to true, the loading indicator appears in the middle of the chart plot to inform the user that the component is currently fetching or processing data. When the loading prop is set to false, the component should display its regular content.

CodeSandbox

CodeSandbox

Download data as CSV

The HistogramChart component supports download data in CSV format using a toolbar button. To enable this feature, a ChartToolbar subcomponent with ChartToolbar.DownloadData inside of it must be provided to the HistogramChart component. On click of the download button, raw data will be downloaded as a CSV file.

The CSV file contains the following columns:

• name - the name of the series
• unit - the unit of the series
• from - the start of the bin range
• to - the end of the bin range
• value - the value of the bin

CodeSandbox

It's also possible to programmatically trigger the download of the CSV file by calling the downloadData method on the HistogramChart instance reference.

CodeSandbox

Styling

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

Props

HistogramChartProps

extends

Name	Type	Default	Description
data	[]	-	Data object for the histogram chart
height?	|	300px	Chart height. When a number is specified, it's treated as pixels, otherwise a valid height string is expected.
seriesActions?	(series: , bin: ) =>	-	Actions to be shown in the legend and tooltip actions
truncationMode?		'middle'	Truncation mode to use (start, middle, end) Applied to all the parts that truncate text.
colorPalette?	|	"categorical"	Color palette to be used for the bar category.
loading?		false	Show the loading indicator when truthy.

HistogramChart.Legend

To configure the legend, add HistogramChart.Legend to the histogram chart.

HistogramChartLegendProps

Signature:

export declare type HistogramChart = ;

HistogramChart.Tooltip

To configure the tooltip, add HistogramChart.Tooltip to the histogram chart.

HistogramChartTooltipProps

Name	Type	Default	Description
variant?		-	Whether the tooltip should contain bins from all series or just the closest one.

HistogramChart.XAxis

To configure the x-axis, add HistogramChart.XAxis to the histogram chart.

HistogramChartXAxisProps

Name	Type	Default	Description
max?	| |	'auto'	The max value configuration to display in the axis
min?	| |	'auto'	The min value configuration to display in the axis
label?		-	The title used for the axis
scale?		-	The scale to be used
formatter?	| <, >	-	Formatter to be applied for each tick of the axis
unit?		-	The unit for the axis

HistogramChart.YAxis

To configure the y-axis, add HistogramChart.YAxis to the histogram chart.

HistogramChartYAxisProps

Name	Type	Default	Description
max?	| |	'auto'	The max value configuration to display in the axis
min?	| |	'auto'	The min value configuration to display in the axis
label?		-	The title used for the axis
scale?		-	The scale to be used
formatter?	| <, >	-	Formatter to be applied for each tick of the axis
position?	|	'left'	The position of the y axis relative to the histogram chart

HistogramChart.Threshold

TimeseriesChart.Threshold provides a slot for defining thresholds in the chart.

HistogramThresholdProps

Name	Type	Default	Description
data		-	The threshold data to be graphed by the component
color		-	The unique color picked for this histogram representation in HEX, RGB, Color Token or HSL.
position?		-	The position of the threshold relative to the histogram chart.
strokeOnly?		-	Whereas to show the ranges filled or only the strokes
label?		"Threshold"	Label to be shown in the threshold tooltip.

HistogramChart.EmptyState

HistogramChart.EmptyState provides a slot where the Empty state wrapper can be set.

EmptyStateProp

Name	Type	Default	Description
children	.	-

HistogramChart.ErrorState

HistogramChart.ErrorState provides a slot where the Error state wrapper can be set.

ErrorStateProps

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

HistogramChart.Annotations

HistogramChart.Annotations provides a slot for configuring annotations in the histogram.

HistogramAnnotationsProps

Name	Type	Default	Description
visibleTracksLimit?		-	How many tracks to show by default, if there are more tracks than the specified here a scrollbar will be added.
showLabels?		false	Optional flag to determine whether to display labels.
annotationsActions?	(annotation: ) =>	-

HistogramAnnotations.Track

HistogramAnnotations.Track provides a slot for configuring the track in the HistogramChart.Annotations.

HistogramAnnotationsTrackProps

Name	Type	Default	Description
color?		-	Color of the track.
label?		-	Optional label for the track.
hidden?		-	Whether this track should be visible
indicatorsDisplay?		-	Defines how to show the annotations indicators: always, never, or on hover (auto) at Track level
symbol?		-	Annotations markers character (letter/emoji/icon/glyph or Unicode character).
priority?		-	Priority for annotation track

HistogramAnnotations.Marker

HistogramAnnotations.Marker provides a slot for configuring the marker in the HistogramChart.Annotations.

HistogramAnnotationsMarkerProps

Name	Type	Default	Description
value		-	Value of the annotation marker
title		-	Title of the annotation.
description?		-	Details about the marker.
color?		-	Color of the marker
indicatorsDisplay?		-	Defines the display behaviour of marker's indicators of a particular track auto - a default behavior. Indicators are only shown on markers hover always - always show the marker indicator never - never shown the marker indicator
symbol?	|	-	Annotation marker character (letter/emoji/icon/glyph or Unicode character).
hidden?		-	Flag to hide a marker
priority?		-	Priority for annotation marker

ChartInteractions

Use the ChartInteractions component for configuring the chart zoom interactions of the chart.

ChartInteractionsProps

Name	Type	Default	Description
toolbar?		-	Shows the interactions toolbar inside the chart
onZoomChange?		-	Callback called when any zoom event has been performed affecting the data timeframe

ChartInteractions.Zoom

Define the ChartInteractions.Zoom component within the ChartInteractions for enabling the zoom in/out of the chart.

ChartInteractions.ZoomX

Define the ChartInteractions.ZoomX component the ChartInteractions for enabling the zoom in the x axis of the chart.

ChartInteractions.Pan

Define the ChartInteractions.Pan component the ChartInteractions for enabling the pan of the chart.