DonutChart

The DonutChart is a variation of a pie chart with a circular shape and a hole in the center. It divides the total amount into proportional slices, each representing a category or value. The key difference is the presence of the central hole, which allows placing additional information in the available space.

Import

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

Use cases

The DonutChart expects an object with an array of slices. Each slice has a category and a value.

The expected value type is number and it is used to derive the relative distribution of the slices. It is also possible to specify the unit if needed.

CodeSandbox

Change the size of a chart

By default, the chart will use the width and height of the available container while using a 1:1 aspect ratio. The height of the container is 300 pixels by default, but both a width and a height specified in pixels can be manually set. If a number is passed to this prop without any unit specified, it will be treated as px.

CodeSandbox

Labels

By default, slice labels are enabled. In order to hide all the labels in the chart, add the subcomponent configuration <DonutChart.Labels hidden/>.

Labels that don't fit a specific slice will be automatically hidden independent of the configuration value setting.

The default values for the labels will be relative but you can also set it to the absolute value, using the valueType prop

CodeSandbox

Change the chart color/s

The DonutChart provides a set of predefined color palettes and it also accepts custom color palettes. See coloring for more details.

Apart from all these options for providing a color palette, the DonutChart also offers the ability to override colors for specific slices. When a color override is specified, it takes precedence over the color that would otherwise be assigned from the color palette. However, it does not affect the colors assigned to other slices. This allows for fine-grained control over the appearance of individual slices within the chart. A color override is done by category. We should specify the category name we want to be overridden and provide the desired color to the DonutChart data using a color prop.

Grouping

The grouping defines a way to aggregate multiple slices into a single one.

The slices are grouped depending on a given threshold prop. All the slices with a value that match the input threshold will be part of the group.

It is possible to specify three different types of thresholds:

• relative: The threshold is the relative value of the slices (distribution in percentage). All values lower than the threshold will be part of the group.
• absolute: The threshold is the absolute value of the slices. All values lower than the threshold will be part of the group.
• number-of-slices: The threshold is the ordinal number of the slices. Once the number of slices specified in the threshold is reached, all the others will be grouped.

By default, the group name is Other. This value can be changed by providing it in the configuration via the name prop.

To configure custom groups, use the subcomponent configuration <DonutChart.Grouping />. If the group configuration is not provided, the grouping is relative: 2% as default.

CodeSandbox

Legend customization

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

Visibility

The legend for the DonutChart will be shown by default, but it can be optionally hidden by making use of the hidden prop on the subcomponent.

Legend position

By default, the legend of the DonutChart is positioned automatically ({position: "auto"}) to the right if it has space or to the bottom if there's no right space. It is also possible to customize the chart's legend position by setting the desired position: right or bottom.

Legend ratio

By default, the legend occupies 75% 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.

The ratio property does not apply any changes in the DonutChart (for keeping the aspect ratio) if the legend is on the right. However, it is possible to override the default legend ratio by setting a custom percentage value for the ratio prop, if the legend is on the bottom. The expected value is in the range of 5-80. Values out of expected ranges will roll back to the default legend ratio.

CodeSandbox

Truncation Mode

The purpose of truncation is to gracefully handle extra long tooltips or legends within data visualization components. By changing the value of this property, you have control over where truncation is applied within charts. By default, the truncation is applied to the middle value with the use of an ellipsis. Truncation can, however be changed to instead be applied at the start or end of data visualization component elements.

CodeSandbox

Formatter

As the DonutChart expects an array of categories with a value and an optional unit, by default this optional unit will be appended to the specified value, if it is included. 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 will appear in the chart tooltip. The use cases below outline each of these scenarios.

CodeSandbox

Total value and inner content

The donut chart component provides the possibility to display custom content within the empty space at its center.

To achieve this, you can utilize the <DonutChart.Inner /> subcomponent. There are two approaches to passing the content to be rendered. The first option is to use the subcomponent and insert a basic React Node or JSX template. Alternatively you can use the function which exposes certain internal information as a parameters. The parameters of the function provide access to various details, such as the absolute value and relative value of the selected slices, as well as the dimensions of the square area where the element will be rendered.

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

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

Loading

The loading prop is a boolean value that can be passed to the DonutChart 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

Download data as CSV

The DonutChart 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 DonutChart component. On click of the download button, raw data will be downloaded as a CSV file.

The CSV file contains the following columns:

• category - the name of the category
• value - the value of the category
• unit - the unit of the category

CodeSandbox

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

CodeSandbox

Styling

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

CodeSandbox

Props

DonutChartProps

extends

Name	Type	Default	Description
data		-	Categorical data of the chart.
width?		-	Chart width. A number in pixels is expected. Otherwise, it will take the full width of the container.
height?	|	300px.	The height of the chart. If a number is passed, it will be treated as px.
colorPalette?	|	'categorical'.	Set of Color palette to be used in charts.
formatter?	| <, >	-	Custom Formatter for the chart
truncationMode?		'middle'	Truncation mode to use (start, middle, end) Applied to all the parts that truncate text.
seriesActions?	(slice: ) =>	-	Exposed callback to display series actions for a slice
loading?		false	Show the loading indicator when truly.

LabelsConfig

Name	Type	Default	Description
hidden?		false (all the labels are displayed).	Hides the slice labels.
valueType?		'relative'	Display the label with a relative or absolute value.

ThresholdConfig

Name	Type	Default	Description
type		'relative'.	Type of the grouping threshold. Can be "relative", "absolute" or "number-of-slices".
value		-	Value of the group threshold. Default is dynamically calculated depending on the chart size for relative and absolute. 10 in case of number-of-slices.

GroupConfig

Name	Type	Default	Description
name?		'Other'.	Name of the group.
threshold		-	The threshold for the group.