PieChart

The PieChart visualizes data proportions in a circular chart. It divides a circle into slices, with each slice representing a specific category or value.

OverviewProperties

Import

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

Use cases

The PieChart expects a data structure composed of an array of slices and an optional unit as a string.

Each slice of the chart should contain the following attributes:

• Category: The name or label for the slice.
• Value: The numerical value representing the size of the slice.
• Color: An optional color assigned to the slice.

Unit: An optional string representing the unit of measurement for the values.

{
  slices: [
    {
      category: 'EMEA',
      value: 66,
    },
  ],
  unit: '$',
}

Learn more about the data format here.

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 hidden prop to the <PieChart.Labels hidden/> subcomponent.

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 PieChart 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 PieChart 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 PieChart data using a color prop.

CodeSandbox

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 <PieChart.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 PieChart 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 PieChart is positioned automatically ({position: "auto"}) to the right, if it has space, or to the bottom if there's not enough space on the right. 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 PieChart (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 PieChart 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

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 PieChart 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 PieChart 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 PieChart 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 PieChart instance reference.

CodeSandbox

Styling

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

CodeSandbox