Version 1.0.0

Donut chart

Donut charts are ideal for comparing proportions of a whole. Each segment of a donut chart is mapped to a dimension value with an arc length determined by a metric.

Donut chart with the number of visitors divided into three segments based on operating system, including Windows, macOS, and Other.Donut chart with the number of visitors divided into three segments based on operating system, including Windows, macOS, and Other.

Anatomy#


Image illustrating through labels the component parts of a donut chart, including the segments, metric total, metric label, and either a legend or direct labels with a label title and label value.Image illustrating through labels the component parts of a donut chart, including the segments, metric total, metric label, and either a legend or direct labels with a label title and label value.

Options#


Key example of a standard donut chart with segments mapped to a circle by operating system that have been color coded in seafoam, indigo, and orange and the total number of visitors displayed numerically in the center of the chart.

Donut chart#

A standard donut chart is a stacked bar chart mapped onto a polar coordinate plane (a circle). The space in the center of the chart is used to provide a total of the displayed metric. A legend or direct labels are required.

Key example of two boolean donut charts, one displaying a positive completion rate in green and the other displaying a negative bounce rate in red. Both charts display the percentage and label for the relevant values in the center.

Boolean#

A boolean donut chart can only show two values: a “positive” or a “negative.” When a positive statement is more relevant information, the segment is shown in a color such as green and the negative is shown in gray. When a negative statement is more relevant, the segment is shown in a color such as red and the positive is shown is grey. These colors can be changed to accommodate different cultural meanings associated with positive and negative sentiment. The center is used to display a percentage and a label for the more relevant (colored) value. A legend is not required.

Key example of a donut chart with direct labels for each segment that include the segment name, percentage of the total, and the metric value for the operating systems Windows, macOS, and other.

Direct labels#

Direct labels are often easier to understand than a legend. When space allows, use direct labels that show the segment name, the percentage of the total, and the metric value.

Key example of a donut chart with a categorical color legend including the operating systems Windows, macOS, and Other color coded in seafoam, indigo, and orange on the chart.

Legend#

When constraints make it impossible to use direct labels, show a categorical color legend. A legend should be positioned to the right of a donut chart, but if there is not enough horizontal space, it can be placed below the chart.

Behaviors#


Key example of one segment of a donut chart being hovered on. All other segments not hovered on fade back, and a tooltip appears above the cursor displaying the detailed information. Tooltip text, Windows, 70.2% of visitors, 24,582 visitors. Second example of one segment of a donut chart being hovered on. All other segments fade to the background and a direct label displays detailed information reading Windows, 70.2%, 24,582.

Hover#

Hovering over a segment of a donut chart causes all other segments to fade back from the view. A tooltip displays the segment name, percentage of total, and metric value.

Key example of one segment of a donut chart being hovered on. All other segments fade to the background and a direct label displays detailed information reading Windows, 70.2%, 24,582.

Selection#

Chart segments can be interactive. When they are, leverage the selected state and surface actions in a panel, rail, or floating menu.

Key example of a donut chart with one segment receiving focus. Selected segment has a focus state plus a gray tooltip above the focus bar displaying the detailed information. Second example of a donut chart with one segment receiving focus. Selected segment has a focus state and the direct label displays detailed information reading Windows, 70.2%, 24,582.

Focus#

A donut chart can be navigated using a keyboard. Focus begins at the twelve o’clock position and moves clockwise around the chart. A blue border is applied to the segment in focus and a tooltip displays the segment name, percentage of total, and metric value.

Key example of a chart in the ghost loading state, with no values or labels displayed.

Loading#

Charts often require time to load, so include a loading state.

Key example of a donut chart that has returned null values, which are treated as zeros and omitted from the chart. The number of omitted values is displayed below the donut chart.

Null values#

When data returns null (blank) values, they should be omitted. An explanation should be included of what was omitted and why.

Key example of an empty chart, so all that shows is a chart icon with the text “No data available.”, and an action to link a dataset.

Empty state#

When there is no data available, a chart should indicate as such and give direction as to how to make data appear there. Do not render an empty chart.

Key example of what happens when there has been an error when fetching data. An error icon appears in place of the chart with the text “Unable to load chart.”, and the option to reload.

Error state#

There are occasionally errors with fetching data. When this happens, give users a helpful, actionable explanation of what happened and what they can do to fix things. Do not render an empty chart.

Usage guidelines#


Use categorical color#

Each segment of a donut chart should have a unique, categorical color. If your data is sequential, use a histogram instead.

Key example of a donut chart correctly using categorical colors for each operating system.
Key example of a donut chart incorrectly using sequential color to display metric values.

Use up to five segments#

Donut charts become difficult to understand when they include many segments. Try to use 2-3 segments if possible, and no more than 5.

Key example of a donut chart with only three segments, helping to increase readability.
Key example of a donut chart with nine segments, making the chart difficult to parse.

Sort segments by metric#

Segments of donut charts should be sorted with the largest value starting in the twelve o’clock position, followed by each smaller value in succession moving in the clockwise direction.

Key example of a donut chart that correctly sorts the segments from largest to smallest.
Key example of a donut chart that incorrectly sorts the segments

Do not segment time#

Time is a sequential variable and should not be used as a category in a donut chart. If showing cyclical time, use a histogram instead.

Key example of a donut chart that incorrectly displays time as a dimension rather than a sequential variable.

Keyboard interactions#


KEYInteraction
Right ArrowMoves focus clockwise to the next segment. If focus is already on the last segment or there are no segments, the focus does not move.
Left ArrowMoves focus counter-clockwise to the next segment. If focus is already on the first segment or there are no segments, the focus does not move.
HomeMoves focus to the first segment of the chart beginning at the twelve o’clock position.
EndMoves focus to the last segment of the chart.
Space or enterTriggers the selection state of a segment.

Changelog#


DateNumberNotes
Mar 03, 20201.0.0
  • This component has been added to the website

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.