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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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 categoryvalue- the value of the categoryunit- the unit of the category
It's also possible to programmatically trigger the download of the CSV file by
calling the downloadData method on the DonutChart instance reference.
Styling
The DonutChart also accepts custom styling, which could be set using the props
className and/or style, as a regular html element