Chart

When to use

Chart shows the shape or trend of a data set at a glance: change by month, a comparison between categories, the shares of a whole. When exact values matter, the chart comes with its table.

Pick the right kind:

• Line (line): change along an ordered axis, time series.
• Area (area): the size and trend of a single series.
• Bar (bar): categories compared side by side.
• Stacked bar (stacked-bar): the parts of a whole in each category.
• Donut (donut): the shares of one series, at most 5 parts.

When not to use

• For a single number: use StatCard for a value and its change.
• To read exact values: use Table or DataTable for rows of records.
• For shares with many parts: more than 5 slices cannot be told apart; use a bar chart or a table.
• As decoration: do not add a chart that carries no information.

Anatomy

1. Figure (figure): the container of the chart, its caption and its table.
2. Caption (figcaption): the required title; titleHidden leaves it for screen readers only.
3. Description: the optional description, linked with aria-describedby.
4. Table button: at the end of the caption row when table="toggle".
5. Drawing: SVG named by role="img" and a summary sentence; a tooltip opens on hover.
6. Legend: at the top start for several series and for a donut; 8 px squares.
7. Data table: the title as caption, categories as row headers, series as column headers.

Behaviour

• The chart appears within 400 ms on first draw. When data changes, series update in place over 240 ms; the entrance does not replay.
• With reduced motion, animation is off.
• While loading, a placeholder block shows and the figure is aria-busy. Without data it says “No data for this period”.
• hideValues removes the axis values; the tooltip, summary and table show ••••.
• The chart follows the width of its container and resizes when the container does.
• Points are not focusable by keyboard; all data is in the table.

Guidelines

A donut has at most 5 parts

More than five slices cannot be told apart. With many parts use a bar chart.

Share of categories

DoFour parts: the slices read clearly.

Share of categories

Don'tEight small slices: the parts cannot be told apart.

A bar axis starts at zero

The length of a bar is the value. Chart starts the axis at zero for you; do not cut the value axis.

Monthly values

DoThe axis starts at zero; proportions read correctly.

Monthly values

Don'tA small difference looks large when the axis starts at 50; Chart does not allow it, use a line chart for close values.

Colour does not carry meaning alone

With several series the lines differ in symbol and style and the bars in pattern. Do not hang the meaning on colour; write series names in the legend and the table.

Monthly values

DoSeries differ by symbol, line style and name.

The red line shows the increase, the blue line the decrease.

Don'tText that only says "red line": the meaning depends on colour.

Content

• Make the title a noun phrase that says what the chart shows: “Monthly values”.
• Keep description to two sentences at most; state the period and the unit.
• Keep series names short: “First series”, “Category A”.
• Format numbers with their unit through formatValue; do not leave raw numbers without a unit.
• Change the empty text to say what to do next with emptyLabel.

Related components

• StatCard: for a single number and a small trend line.
• Card: to put a chart on one surface with a title and actions.
• Button: the table toggle is drawn with this component.