4.46.4

Donut

Donut chart component for displaying data distribution with optional center text and legend

Demo

API

Tag

Name Description
<aui-donut> Custom HTML tag

Attributes

Name Value Required Description
data Array of numbers or JSON string

Array of numeric values representing the data segments. The values determine the proportional size of each segment in the donut chart. Can be provided as an array (e.g., [30, 25, 20, 15, 10]) or JSON string (e.g., "[30, 25, 20, 15, 10]"). When the array is empty or no data is provided, the component displays an empty state message.
labels Array of strings or JSON string

Optional array of labels for each data segment. Can be provided as an array or JSON string.
colors Array of color strings or JSON string

Optional array of colors for each segment. Can be provided as an array or JSON string. Colors can be named colors (e.g., "--color-red-medium") or named gradients (e.g., "--gradient-teal-medium"). See Colors and Gradients documentation for available options. If not provided, default gradient colors will be used.
centervalue String

Text to display in the center of the donut chart (e.g., "9,999").
centerlabel String

Optional label text to display below the center value.
legendlabels Array of strings or JSON string

Optional array of primary labels for the legend. Each label corresponds to a data segment and is displayed in bold. The legend appears to the right of the donut chart when provided. Can be provided as an array or JSON string (e.g., "['Label A', 'Label B', 'Label C']").
legendsublabels Array of strings or JSON string

Optional array of secondary labels for the legend. Each label corresponds to a data segment and appears below the primary label in regular font weight. Can be provided as an array or JSON string (e.g., "['Sub A', 'Sub B', 'Sub C']").
pie Boolean

When set to true, renders the chart as a pie chart (no center cutout) instead of a donut chart. Center text is not displayed for pie charts.
aria-label String

Accessibility label for the donut chart.
i18n string

A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name Value Required Description
data Array of numbers or string

Array of numeric values representing the data segments. Can be provided as an array or JSON string. When the array is empty or no data is provided, the component displays an empty state message.
labels Array of strings or string

Optional array of labels for each data segment. Can be provided as an array or JSON string.
colors Array of strings or string

Optional array of colors for each segment. Can be provided as an array or JSON string. Colors can be hex values (e.g., "#059BD2"), CSS color variables (e.g., "--color-red-medium"), or CSS gradient variables (e.g., "--gradient-teal-medium"). See Colors and Gradients documentation for available options. If not provided, default gradient colors will be used.
centerValue String

Text to display in the center of the donut chart (e.g., "9,999").
centerLabel String

Optional label text to display below the center value.
legendLabels Array of strings or string

Optional array of primary labels for the legend. Each label corresponds to a data segment.
legendSubLabels Array of strings or string

Optional array of secondary labels for the legend. Each label corresponds to a data segment and appears below the primary label.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Demo

Tag

Name
<AuiDonut>

Props

Name Value Required Description
data Array of numbers or string

Array of numeric values representing the data segments. Can be provided as an array or JSON string. When the array is empty or no data is provided, the component displays an empty state message.
labels Array of strings or string

Optional array of labels for each data segment. Can be provided as an array or JSON string.
colors Array of strings or string

Optional array of colors for each segment. Can be provided as an array or JSON string. Colors can be hex values (e.g., "#059BD2"), CSS color variables (e.g., "--color-red-medium"), or CSS gradient variables (e.g., "--gradient-teal-medium"). See Colors and Gradients documentation for available options. If not provided, default gradient colors will be used.
centerValue String

Text to display in the center of the donut chart (e.g., "9,999").
centerLabel String

Optional label text to display below the center value.
legendLabels Array of strings or string

Optional array of primary labels for the legend. Each label corresponds to a data segment.
legendSubLabels Array of strings or string

Optional array of secondary labels for the legend. Each label corresponds to a data segment and appears below the primary label.
pie Boolean

When set to true, renders the chart as a pie chart (no center cutout) instead of a donut chart. Center text is not displayed for pie charts.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Skylab React links

General information about using our React package

i18n Strings

ID Description Default value
skylab.donut.emptyStateMessage Message displayed when there is no data to show in the chart This chart updates when data arrives

Guidelines

Usage

The donut chart component is ideal for displaying proportional data distribution. Use it when you need to show:

  • Parts of a whole (e.g., percentage breakdowns, category distributions)
  • Data with a total or summary value in the center
  • Multiple data segments that benefit from a visual legend

Data Format

The data attribute accepts an array of numbers. The values don't need to sum to 100 - the component automatically calculates proportions. For example:

  • data="[30, 25, 20, 15, 10]" - Creates 5 segments with relative sizes
  • data="[100, 200, 150]" - Creates 3 segments proportional to these values
  • data="[]" or no data - Displays an empty state message

Empty State

When no data is provided (empty array or missing data attribute), the component displays an empty state with a message indicating that the chart will appear once data is available.

Legend

When using the legend feature:

  • Provide legendlabels to display primary labels (shown in bold)
  • Optionally provide legendsublabels for secondary information (shown in regular font)
  • The legend automatically matches colors to chart segments
  • The legend appears to the right of the chart and is vertically stacked

Colors

If no custom colors are provided, the component uses default teal and blue gradient colors. To customize:

  • Provide a colors array with hex color values or gradient definitions
  • Each color corresponds to a data segment in order
  • Colors can be hex values: colors='["#059BD2", "#2ed1cc", "#29bcb8"]'
  • Colors can be gradients using the format "gradient:color1:color2": colors='["gradient:#2ED1CC:#29BCB8", "gradient:#015F87:#015578"]'
  • You can mix hex colors and gradients in the same array

Accessibility

Always provide an aria-label attribute on the <aui-donut> element to describe the chart for screen readers. The aria-label will be applied to the child <canvas> element. For example:

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com