On this page

Charts

StackedAreaChart

A total over time and what it is made of. StackedAreaChart stacks one layer per series over an ordered x, with the first series on the baseline, and handles the scales, the tooltip, the keyboard and the screen reader. The x is a category or a date, as in LineChart, and a forecast part is hatched.

When to use it #

Use it when the total over time matters and so does its composition: crew hours per week split by type of work, tickets per month split by priority. Keep it to about five series, because the tones repeat from the sixth. The top of each layer is the running sum, so only the first layer reads against a flat baseline: to compare series with each other, use LineChart. For a total per category rather than over time, use StackedBarChart. It has no target line, no 100 % stacks and no smoothing.

Import #

Terminal
npm i tally-charts
app/hours.tsx
import { StackedAreaChart } from 'tally-charts'
import 'tally-charts/theme.css'

Examples #

Each series says which field it reads and how to name it. The first series sits on the baseline, and the others stack on it in the order of the series array. Props stay serializable here, so the chart renders in a server component. The third series sets tone: 'neutral' in its series object.

Crew hours per week, by type of work
View of Crew hours per week, by type of work
Crew hours per week, by type of work
WeekInstallServiceWarrantyTotal
W118012060360
W219012555370
W320011865383
W421013068408
W520514062407
W622013858416
W723514566446
W824015072462
W925015570475

End labels #

At the right edge of each layer the chart writes the series name and its last value, and the right margin grows to fit them. endLabels={false} turns them off. None is drawn for a layer that is zero at the last x, and none at all when the last row is incomplete or when no area reaches the last x (it is outside the x domain, or it is a lone x after an incomplete row). When the centres of two neighbouring labels would be closer than 36 px, no label is drawn, so a chart with many thin layers has none: compose a Legend instead. Long series names take plot width, because the margin grows with the longest label; use endLabels={false} and a Legend on narrow charts. A margin.right you pass overrides the grown margin, so labels can clip. A chart with a single row has no end labels.

Forecast #

forecastFrom is the first forecast x. The dashed rule sits at the x before it, with forecastLabel above it, and the layers are hatched from the rule to the end. With forecastFrom="W10" the rule is at W9, so the interval that leads into the first forecast x is already hatched. When no x comes before forecastFrom, nothing is hatched and there is no rule. A value that is not on the axis hatches nothing and warns in development. xAxis={6} asks for about six ticks: tick lists are numeric only, so labelling every other category takes a tick count.

Crew hours per week, booked from W10
View of Crew hours per week, booked from W10

Time axis #

With x={{ field: 'date', type: 'time' }} the rows are sorted by date and spaced by time, as in LineChart. On a time axis forecastFrom can be any date: the rule sits at the last row before it, and the layers are hatched from there. A forecastFrom later than every date puts the rule at the last x and hatches nothing. The tick labels, the tooltip headers and the announcements share xAxisFormat, which is 'auto' for dates.

Crew hours per month
View of Crew hours per month

Legend #

The chart has no legend of its own. Compose Legend with the same tones, as with LineChart. For a series without a tone, use the tone from the default order. A hatched item such as “Booked” explains the forecast part.

Crew hours per week, with a legend
View of Crew hours per week, with a legend

Series and tones #

An AreaSeries has an id that is unique within the chart, a label for the end label, the tooltip, the announcements and the data table header, a value accessor, and optionally a tone. Without a tone, series take the tones by position: accent, accent-soft, warn, neutral, gain, and then the order repeats. The default order never uses loss; choose it explicitly. A thin line in the surface colour separates neighbouring solid layers, in forced colors mode too; a hatched layer gets an edge line in its tone.

Negative and missing values #

A negative value counts as zero in the layers and in the total, with a warning in development, while the tooltip and the data table show the real value. A missing or non-numeric value breaks every layer at that x: the layers end on both sides of it, and an x between two breaks draws no area. The row still has a point that lists the series that have a value, and it has no total. The default value domain runs from zero to the largest total, rounded to nice ticks.

Props #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

chartIdstring—No

Prefix for pattern and mask ids. React's useId is only unique within one root, so set this when charts render in several React roots on one page.

childrenReactNode—No—
classNamestring—No—
datareadonly D[]—Yes—
dataTableboolean | DataTableOptionstrueNo

Hidden data table for screen readers: true, false, or { caption, columns } to set its caption and rename column headers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
domainreadonly [number, number]zero to the largest total, rounded to nice ticksNo

Value domain. Default: zero to the largest total, rounded to nice ticks.

emptyReactNode"No data"No

Rendered instead of the plot when data is an empty array. Default "No data".

endLabelsbooleantrueNo

Series name and last value at the right edge of each layer. Default true.

forecastFromTimeInput—No

The first forecast x: a category, or any date on a time axis. The layers are hatched from the last x before it to the end, and a dashed rule sits at that last x before it (with forecastFrom="W10", at W9). Nothing is hatched when no x comes before it.

forecastLabelstring—No

Text above the rule, e.g. "today".

formatFormatSpec'number'No

Default 'number'.

gridbooleantrueNo

Horizontal grid lines at the value ticks ('all' when yAxis is 'none'). Default true.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

initialWidthnumber640No

Width used for server rendering and the first client render. Default 640.

interactivebooleantrueNo

Default true. With false the chart is static: no points are registered, so it has no tab stop, no keyboard hint, no pointer response and no tooltip (tooltip is ignored), and onSelect and onActiveChange never fire. The title and the data table stay.

keyboardHintstring"Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with `onSelect`No

Instructions read with the chart when it takes keyboard focus. Default: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with onSelect. A custom text is used as is. Set it to translate the text; "" turns it off.

marginPartial<Margin>—No—
onActiveChange(id: Id | null, point: ChartPoint<D> | null) => void—No

Called with the new active id, and its point; point.datum is the row from data.

onSelect(id: Id, point: ChartPoint<D>) => void—No

Called on click, Enter or Space; point.datum is the row from data.

seriesreadonly AreaSeries<D>[]—Yes

One layer per series; the first series sits on the baseline. A negative value counts as zero; a missing or non-numeric value breaks every layer at that x.

styleCSSProperties—No—
titlestring—No

Accessible name of the chart; also the default caption of the data table.

tooltipChartTooltip<D>trueNo

Tooltip on hover and focus: true for the default pill, or a function that renders the content for a point (point.datum is your row). Default true.

widthnumber—No

Fixed width in px; turns off container measuring.

xAccessor<D, string | number> | (TimeScaleSpec<D> & { field: Accessor<D, TimeInput> })—Yes

As LineChart: an accessor puts categories on a point scale, a time scale spec with a field puts dates on a time axis (rows sorted by date).

xAxisTickSpec | 'none''all'No

x axis ticks, or 'none'. Default 'all'.

xAxisFormatAxisFormatthe category itself, or 'auto' dates on a time axisNo

x axis labels; tooltip headers, announcements and the data table's x cells use the same format. Default: the category itself, or 'auto' dates on a time axis.

yAxisTickSpec | 'none''all' (about 5)No

Value axis ticks, or 'none'. The grid follows them. Default 'all' (about 5).

yAxisFormatAxisFormat`format`No

Value axis labels. Default: format.

Series and points #

There is one point per x, not per series, and its id is the row key: the category as a string, or the ISO date. A row with no value at all has no point. In onSelect and onActiveChange, the ChartPoint has your row as datum. The default tooltip shows the x, then the series with their tone swatches and values, the top layer first, and then the total (a complete row only). The active x gets a cursor: for a complete row a line from the baseline to the top of the stack with a dot on each layer, and for a row with a missing value a line to the top of the plot and no dots.

Keyboard and screen readers #

The chart is a single tab stop. The arrow keys move from one x to the next and back, Home and End jump to the first and last, Enter or Space selects the active x when the chart has onSelect, and Esc clears it. Hovering snaps to the nearest x. With interactive={false} the chart registers no points, so it has no tab stop, no tooltip and no cursor; the title, the end labels and the data table stay.

Screen readers get the title and description, then an announcement for each x the keyboard moves to, such as “2 of 12, W2, 55 h Warranty, 125 h Service, 190 h Install, 370 h Total”: the position, the x, then the series from the top layer down and the total. A visually hidden data table follows the chart, with one row per x, one column per series and a last column with the total. It does not mark the forecast rows, so say in the title or the description which part is a forecast, as the examples do.

The full model is in the accessibility guide.