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 #
npm i tally-chartsimport { 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.
| Week | Install | Service | Warranty | Total |
|---|---|---|---|---|
| W1 | 180 | 120 | 60 | 360 |
| W2 | 190 | 125 | 55 | 370 |
| W3 | 200 | 118 | 65 | 383 |
| W4 | 210 | 130 | 68 | 408 |
| W5 | 205 | 140 | 62 | 407 |
| W6 | 220 | 138 | 58 | 416 |
| W7 | 235 | 145 | 66 | 446 |
| W8 | 240 | 150 | 72 | 462 |
| W9 | 250 | 155 | 70 | 475 |
import { StackedAreaChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'stacked-area-chart/hours-by-type',
title: 'Crew hours per week, by type of work',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', install: 180, service: 120, warranty: 60 },
{ week: 'W2', install: 190, service: 125, warranty: 55 },
{ week: 'W3', install: 200, service: 118, warranty: 65 },
{ week: 'W4', install: 210, service: 130, warranty: 68 },
{ week: 'W5', install: 205, service: 140, warranty: 62 },
{ week: 'W6', install: 220, service: 138, warranty: 58 },
{ week: 'W7', install: 235, service: 145, warranty: 66 },
{ week: 'W8', install: 240, service: 150, warranty: 72 },
{ week: 'W9', install: 250, service: 155, warranty: 70 },
]
// Props stay serializable (no functions): the page is a server component.
export default function HoursByType() {
return (
<StackedAreaChart
data={weeks}
x="week"
series={[
{ id: 'install', label: 'Install', value: 'install' },
{ id: 'service', label: 'Service', value: 'service' },
{ id: 'warranty', label: 'Warranty', value: 'warranty', tone: 'neutral' },
]}
height={260}
title={meta.title}
description="Install is the largest part of the hours every week and grows from 180 to 250 hours."
/>
)
}
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.
import { StackedAreaChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'stacked-area-chart/booked-weeks',
title: 'Crew hours per week, booked from W10',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', install: 180, service: 120, warranty: 60 },
{ week: 'W2', install: 190, service: 125, warranty: 55 },
{ week: 'W3', install: 200, service: 118, warranty: 65 },
{ week: 'W4', install: 210, service: 130, warranty: 68 },
{ week: 'W5', install: 205, service: 140, warranty: 62 },
{ week: 'W6', install: 220, service: 138, warranty: 58 },
{ week: 'W7', install: 235, service: 145, warranty: 66 },
{ week: 'W8', install: 240, service: 150, warranty: 72 },
{ week: 'W9', install: 250, service: 155, warranty: 70 },
{ week: 'W10', install: 255, service: 158, warranty: 74 },
{ week: 'W11', install: 262, service: 162, warranty: 76 },
{ week: 'W12', install: 270, service: 165, warranty: 78 },
]
// `xAxis={6}` asks for about six ticks, so every other week is labelled.
export default function BookedWeeks() {
return (
<StackedAreaChart
data={weeks}
x="week"
series={[
{ id: 'install', label: 'Install', value: 'install' },
{ id: 'service', label: 'Service', value: 'service' },
{ id: 'warranty', label: 'Warranty', value: 'warranty', tone: 'neutral' },
]}
forecastFrom="W10"
forecastLabel="today"
xAxis={6}
height={260}
title={meta.title}
description="Weeks 1 to 9 are worked hours and weeks 10 to 12 are booked; the total grows from 360 to 513 hours."
/>
)
}
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.
import { StackedAreaChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'stacked-area-chart/time-axis',
title: 'Crew hours per month',
rscSafe: true,
} satisfies ExampleMeta
const months = [
{ date: '2026-01-01', install: 180, service: 120, warranty: 60 },
{ date: '2026-02-01', install: 190, service: 125, warranty: 55 },
{ date: '2026-03-01', install: 200, service: 118, warranty: 65 },
{ date: '2026-04-01', install: 210, service: 130, warranty: 68 },
{ date: '2026-05-01', install: 205, service: 140, warranty: 62 },
{ date: '2026-06-01', install: 220, service: 138, warranty: 58 },
{ date: '2026-07-01', install: 235, service: 145, warranty: 66 },
{ date: '2026-08-01', install: 240, service: 150, warranty: 72 },
]
// On a time axis `forecastFrom` can be any date; the rule sits at the last month before it (June here).
export default function TimeAxis() {
return (
<StackedAreaChart
data={months}
x={{ field: 'date', type: 'time' }}
series={[
{ id: 'install', label: 'Install', value: 'install' },
{ id: 'service', label: 'Service', value: 'service' },
{ id: 'warranty', label: 'Warranty', value: 'warranty', tone: 'neutral' },
]}
forecastFrom="2026-07-01"
forecastLabel="today"
height={260}
title={meta.title}
description="Hours grow from January to August; the rule is at June, and July and August are booked."
/>
)
}
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.
import { Legend, StackedAreaChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'stacked-area-chart/with-legend',
title: 'Crew hours per week, with a legend',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', install: 180, service: 120, warranty: 60 },
{ week: 'W2', install: 190, service: 125, warranty: 55 },
{ week: 'W3', install: 200, service: 118, warranty: 65 },
{ week: 'W4', install: 210, service: 130, warranty: 68 },
{ week: 'W5', install: 205, service: 140, warranty: 62 },
{ week: 'W6', install: 220, service: 138, warranty: 58 },
{ week: 'W7', install: 235, service: 145, warranty: 66 },
{ week: 'W8', install: 240, service: 150, warranty: 72 },
{ week: 'W9', install: 250, service: 155, warranty: 70 },
{ week: 'W10', install: 255, service: 158, warranty: 74 },
{ week: 'W11', install: 262, service: 162, warranty: 76 },
{ week: 'W12', install: 270, service: 165, warranty: 78 },
]
// With `endLabels={false}` the layers carry no names: compose `Legend` with the same tones and a hatched
// "Booked" item for the forecast.
export default function WithLegend() {
return (
<div>
<Legend
items={[
{ label: 'Install', tone: 'accent' },
{ label: 'Service', tone: 'accent-soft' },
{ label: 'Warranty', tone: 'neutral' },
{ label: 'Booked', tone: 'accent', fill: 'hatch' },
]}
/>
<StackedAreaChart
data={weeks}
x="week"
series={[
{ id: 'install', label: 'Install', value: 'install' },
{ id: 'service', label: 'Service', value: 'service' },
{ id: 'warranty', label: 'Warranty', value: 'warranty', tone: 'neutral' },
]}
forecastFrom="W10"
forecastLabel="today"
endLabels={false}
xAxis={6}
height={260}
title={meta.title}
description="Install is the largest part of the hours every week; weeks 10 to 12 are booked."
/>
</div>
)
}
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 #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | Id | null | — | No | — |
animate | boolean | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
chartId | string | — | No | Prefix for pattern and mask ids. React's |
children | ReactNode | — | No | — |
className | string | — | No | — |
data | readonly D[] | — | Yes | — |
dataTable | boolean | DataTableOptions | true | No | Hidden data table for screen readers: |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
domain | readonly [number, number] | zero to the largest total, rounded to nice ticks | No | Value domain. Default: zero to the largest total, rounded to nice ticks. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
endLabels | boolean | true | No | Series name and last value at the right edge of each layer. Default true. |
forecastFrom | TimeInput | — | 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 |
forecastLabel | string | — | No | Text above the rule, e.g. "today". |
format | FormatSpec | 'number' | No | Default 'number'. |
grid | boolean | true | No | Horizontal grid lines at the value ticks ('all' when |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
initialWidth | number | 640 | No | Width used for server rendering and the first client render. Default 640. |
interactive | boolean | true | No | 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 ( |
keyboardHint | string | "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 |
margin | Partial<Margin> | — | No | — |
onActiveChange | (id: Id | null, point: ChartPoint<D> | null) => void | — | No | Called with the new active id, and its point; |
onSelect | (id: Id, point: ChartPoint<D>) => void | — | No | Called on click, Enter or Space; |
series | readonly 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. |
style | CSSProperties | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus: |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | Accessor<D, string | number> | (TimeScaleSpec<D> & { field: Accessor<D, TimeInput> }) | — | Yes | As |
xAxis | TickSpec | 'none' | 'all' | No | x axis ticks, or 'none'. Default 'all'. |
xAxisFormat | AxisFormat | the category itself, or 'auto' dates on a time axis | No | 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. |
yAxis | TickSpec | 'none' | 'all' (about 5) | No | Value axis ticks, or 'none'. The grid follows them. Default 'all' (about 5). |
yAxisFormat | AxisFormat | `format` | No | Value axis labels. Default: |
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.