Charts
ScatterChart
Two measures against each other, with an optional third as size. ScatterChart draws one point per row on two value axes, x and y: a dot, or with size a bubble whose area follows the value. It handles the scales, the tooltip, the keyboard and the screen reader.
When to use it #
Use it to ask whether two measures move together, and which rows break the pattern: margin against job size, hours against estimate, price against rating. Add size for a third measure, such as crew hours, and a target line on y to see which rows fall short. Both axes are linear and numeric. For a value per category use BarChart, for values along an ordered x use LineChart, and for the spread of one measure per row use StripPlot. It has no trend line, no log scale or time axis, no zoom or brush, and no size legend.
Import #
npm i tally-chartsimport { ScatterChart } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
x and y say which numeric field each axis reads. Without size every point is a dot of radius (default 5 px). label names the row in the tooltip, the announcement and the data table, and xLabel and yLabel name the measures. Props stay serializable here (field names, a preset format and a constant tone), so the chart renders in a server component.
| Name | Crew hours | Margin, % |
|---|---|---|
| Alder Court | 40 | 44 |
| Birch Lane | 58 | 38 |
| Cedar Row | 40 | 52 |
| Dune House | 103 | 41 |
| Elm Terrace | 79 | 35 |
| Fern Hill | 103 | 46 |
| Grove Flats | 160 | 33 |
| Hazel Yard | 160 | 39 |
| Ivy Works | 231 | 36 |
| Juniper Mill | 520 | 34 |
| Kestrel Barn | 79 | 29 |
| Larch Depot | 130 | 24 |
| Maple Arcade | 231 | 18 |
| North Quay | 271 | 27 |
| Orchard Mews | 361 | 30 |
| Harbor Lofts | 410 | 12 |
import { ScatterChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'scatter-chart/crew-days',
title: 'Margin by crew hours, one dot per job',
rscSafe: true,
} satisfies ExampleMeta
const jobs = [
{ name: 'Alder Court', estimate: 8000, margin: 44, hours: 40 },
{ name: 'Birch Lane', estimate: 12000, margin: 38, hours: 58 },
{ name: 'Cedar Row', estimate: 15000, margin: 52, hours: 40 },
{ name: 'Dune House', estimate: 22000, margin: 41, hours: 103 },
{ name: 'Elm Terrace', estimate: 26000, margin: 35, hours: 79 },
{ name: 'Fern Hill', estimate: 34000, margin: 46, hours: 103 },
{ name: 'Grove Flats', estimate: 38000, margin: 33, hours: 160 },
{ name: 'Hazel Yard', estimate: 48000, margin: 39, hours: 160 },
{ name: 'Ivy Works', estimate: 60000, margin: 36, hours: 231 },
{ name: 'Juniper Mill', estimate: 88000, margin: 34, hours: 520 },
{ name: 'Kestrel Barn', estimate: 18000, margin: 29, hours: 79 },
{ name: 'Larch Depot', estimate: 30000, margin: 24, hours: 130 },
{ name: 'Maple Arcade', estimate: 44000, margin: 18, hours: 231 },
{ name: 'North Quay', estimate: 55000, margin: 27, hours: 271 },
{ name: 'Orchard Mews', estimate: 74000, margin: 30, hours: 361 },
{ name: 'Harbor Lofts', estimate: 68000, margin: 12, hours: 410 },
]
// Without `size` every point is a dot. Props stay serializable (field names, a preset format and a
// constant tone): the page is a server component.
export default function CrewDays() {
return (
<ScatterChart
data={jobs}
x="hours"
y="margin"
label="name"
xLabel="Crew hours"
yLabel="Margin, %"
target={{ value: 32, label: 'target 32%' }}
height={260}
title={meta.title}
description="16 jobs. Harbor Lofts, at 410 crew hours, has the lowest margin, 12%."
/>
)
}
Bubbles #
With size the area of each point follows the value: the row with the largest size in the data gets maxRadius (default 18 px), also when an explicit domain leaves that row out, so bubble sizes do not change when a domain narrows; the others scale with the square root of their size, but none is drawn smaller than 3 px. A size of zero is drawn at that minimum too. Larger bubbles are drawn first, so a small bubble stays visible on top of a large one; equal sizes keep the data order. sizeLabel and sizeFormat name and format the value in the tooltip, the announcement and the data table. The size is never drawn as text.
tone is per item: a tone, or a function of the row (default accent). Passing a function makes the example a client component, as does a format function. The example below colours the jobs under the margin target with loss, and writes the y and size formats as functions.
'use client'
import { ScatterChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'scatter-chart/job-size-margin',
title: 'Margin by job size, bubble area is crew hours',
rscSafe: false,
} satisfies ExampleMeta
const jobs = [
{ name: 'Alder Court', estimate: 8000, margin: 44, hours: 40 },
{ name: 'Birch Lane', estimate: 12000, margin: 38, hours: 58 },
{ name: 'Cedar Row', estimate: 15000, margin: 52, hours: 40 },
{ name: 'Dune House', estimate: 22000, margin: 41, hours: 103 },
{ name: 'Elm Terrace', estimate: 26000, margin: 35, hours: 79 },
{ name: 'Fern Hill', estimate: 34000, margin: 46, hours: 103 },
{ name: 'Grove Flats', estimate: 38000, margin: 33, hours: 160 },
{ name: 'Hazel Yard', estimate: 48000, margin: 39, hours: 160 },
{ name: 'Ivy Works', estimate: 60000, margin: 36, hours: 231 },
{ name: 'Juniper Mill', estimate: 88000, margin: 34, hours: 520 },
{ name: 'Kestrel Barn', estimate: 18000, margin: 29, hours: 79 },
{ name: 'Larch Depot', estimate: 30000, margin: 24, hours: 130 },
{ name: 'Maple Arcade', estimate: 44000, margin: 18, hours: 231 },
{ name: 'North Quay', estimate: 55000, margin: 27, hours: 271 },
{ name: 'Orchard Mews', estimate: 74000, margin: 30, hours: 361 },
{ name: 'Harbor Lofts', estimate: 68000, margin: 12, hours: 410 },
]
// `tone` and the formats are functions, so this example is a client component.
export default function JobSizeMargin() {
return (
<ScatterChart
data={jobs}
x="estimate"
y="margin"
size="hours"
label="name"
xLabel="Estimate"
yLabel="Margin"
sizeLabel="Hours"
xFormat="currency-compact"
yFormat={(v) => `${v}%`}
sizeFormat={(v) => `${v} h`}
tone={(j) => (j.margin < 32 ? 'loss' : 'accent')}
target={{ value: 32, label: 'target 32%' }}
height={260}
title={meta.title}
description="16 jobs. Six of them are below the 32% target; Juniper Mill, the largest bubble, is just above it."
/>
)
}
Target #
target draws a horizontal line on y: a number, or { value, label }. The label sits outside the plot, to the right of it, and the right margin grows to fit it (a margin.right you pass overrides that). A bare number draws the line without a label. The default y domain reaches the target, so a target above every point still fits. With an explicit yDomain that does not contain the target, there is no line and no label.
Axis names #
When xLabel or yLabel is set, the name is also drawn on the chart: the x name under the right end of the x axis, the y name above the y axis, and the plot margin grows to make room. Without them nothing is drawn, and the tooltip, the announcement and the data table use the field name in sentence case (estimate becomes “Estimate”), or “X”, “Y” and “Size” when the accessor is a function. xAxis={'none'} or yAxis={'none'} hides an axis together with its name.
Domains #
By default each domain is the range of the drawn values including zero, rounded to nice ticks; the y domain also includes the target. xDomain and yDomain fix them. A row outside an explicit domain is not drawn and gives no warning, but it keeps its row in the data table. xAxis and yAxis take a tick spec (a count, a list of values, 'all', 'ends') or 'none', and grid={false} removes the horizontal grid lines.
import { ScatterChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'scatter-chart/fixed-domains',
title: 'Margin by job size, both axes fixed',
rscSafe: true,
} satisfies ExampleMeta
const jobs = [
{ name: 'Alder Court', estimate: 8000, margin: 44, hours: 40 },
{ name: 'Birch Lane', estimate: 12000, margin: 38, hours: 58 },
{ name: 'Cedar Row', estimate: 15000, margin: 52, hours: 40 },
{ name: 'Dune House', estimate: 22000, margin: 41, hours: 103 },
{ name: 'Elm Terrace', estimate: 26000, margin: 35, hours: 79 },
{ name: 'Fern Hill', estimate: 34000, margin: 46, hours: 103 },
{ name: 'Grove Flats', estimate: 38000, margin: 33, hours: 160 },
{ name: 'Hazel Yard', estimate: 48000, margin: 39, hours: 160 },
{ name: 'Ivy Works', estimate: 60000, margin: 36, hours: 231 },
{ name: 'Juniper Mill', estimate: 88000, margin: 34, hours: 520 },
{ name: 'Kestrel Barn', estimate: 18000, margin: 29, hours: 79 },
{ name: 'Larch Depot', estimate: 30000, margin: 24, hours: 130 },
{ name: 'Maple Arcade', estimate: 44000, margin: 18, hours: 231 },
{ name: 'North Quay', estimate: 55000, margin: 27, hours: 271 },
{ name: 'Orchard Mews', estimate: 74000, margin: 30, hours: 361 },
{ name: 'Harbor Lofts', estimate: 68000, margin: 12, hours: 410 },
]
// A row outside an explicit domain is not drawn (Juniper Mill, $88K, is left out), and the default
// grid and axes follow the domains.
export default function FixedDomains() {
return (
<ScatterChart
data={jobs}
x="estimate"
y="margin"
size="hours"
label="name"
xLabel="Estimate"
yLabel="Margin, %"
sizeLabel="Hours"
xFormat="currency-compact"
xDomain={[0, 80000]}
yDomain={[0, 60]}
maxRadius={14}
height={260}
title={meta.title}
description="The same jobs on fixed axes: estimates up to $80K and margins up to 60%. The $88K job is outside the domain."
/>
)
}
Legend #
The chart has no legend of its own. Compose Legend with the same tones, as with LineChart. Tone is the only carrier of the grouping in the picture, so keep the grouping in the data as well: the tooltip and the data table show the numbers behind it.
'use client'
import { Legend, ScatterChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'scatter-chart/with-legend',
title: 'Margin by job size, with a legend',
rscSafe: false,
} satisfies ExampleMeta
const jobs = [
{ name: 'Alder Court', estimate: 8000, margin: 44, hours: 40 },
{ name: 'Birch Lane', estimate: 12000, margin: 38, hours: 58 },
{ name: 'Cedar Row', estimate: 15000, margin: 52, hours: 40 },
{ name: 'Dune House', estimate: 22000, margin: 41, hours: 103 },
{ name: 'Elm Terrace', estimate: 26000, margin: 35, hours: 79 },
{ name: 'Fern Hill', estimate: 34000, margin: 46, hours: 103 },
{ name: 'Grove Flats', estimate: 38000, margin: 33, hours: 160 },
{ name: 'Hazel Yard', estimate: 48000, margin: 39, hours: 160 },
{ name: 'Ivy Works', estimate: 60000, margin: 36, hours: 231 },
{ name: 'Juniper Mill', estimate: 88000, margin: 34, hours: 520 },
{ name: 'Kestrel Barn', estimate: 18000, margin: 29, hours: 79 },
{ name: 'Larch Depot', estimate: 30000, margin: 24, hours: 130 },
{ name: 'Maple Arcade', estimate: 44000, margin: 18, hours: 231 },
{ name: 'North Quay', estimate: 55000, margin: 27, hours: 271 },
{ name: 'Orchard Mews', estimate: 74000, margin: 30, hours: 361 },
{ name: 'Harbor Lofts', estimate: 68000, margin: 12, hours: 410 },
]
// The tone is the only carrier of "below target" in the picture: compose `Legend` with the same
// tones. The tooltip and the data table carry the margin as a number.
export default function WithLegend() {
return (
<div>
<Legend
shape="dot"
items={[
{ label: 'At or above 32%', tone: 'accent' },
{ label: 'Below 32%', tone: 'loss' },
]}
/>
<ScatterChart
data={jobs}
x="estimate"
y="margin"
size="hours"
label="name"
xLabel="Estimate"
yLabel="Margin, %"
sizeLabel="Hours"
xFormat="currency-compact"
tone={(j) => (j.margin < 32 ? 'loss' : 'accent')}
target={32}
height={260}
title={meta.title}
description="Jobs below the 32% margin target are red; bubble area is crew hours."
/>
</div>
)
}
Rows that are not drawn #
A row is skipped, with a warning in development, when x or y is not a number, or when size is set and the size is missing, not a number or negative. A skipped row is not a point: it has no bubble, no tooltip and no stop for the keyboard. It does keep its row in the data table, with the table's usual placeholder in the cell of a missing value. A chart whose data is an empty array shows the “No data” message; if every row is skipped, the plot is drawn with no points.
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 | — |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
grid | boolean | true | No | Horizontal grid lines at the y ticks. Default true. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | the data index | No | Point id. Default: the data index. |
initialWidth | number | 640 | No | Width used for server rendering and the first client render. Default 640. |
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 |
label | Accessor<D, string> | — | No | Item name for tooltips, announcements and the data table. |
margin | Partial<Margin> | — | No | — |
maxRadius | number | 18 | No | Radius in px of the bubble with the largest |
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; |
radius | number | 5 | No | Dot radius in px when |
size | Accessor<D, number> | — | No | A third measure drawn as the area of each point (a bubble chart). Without it every point is a dot of |
sizeFormat | FormatSpec | 'number' | No | Default 'number'. |
sizeLabel | string | the field name, or "Size" | No | As |
style | CSSProperties | — | No | — |
target | number | { value: number; label?: string } | — | No | A horizontal target line on y, optionally with a label. |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tone | PerItem<D, Tone> | 'accent' | No | Default 'accent'. |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus: |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | Accessor<D, number> | — | Yes | Horizontal position: a number per row. |
xAxis | TickSpec | 'none' | — | No | — |
xAxisFormat | AxisFormat | `xFormat` | No | Default: |
xDomain | readonly [number, number] | the range of x including zero, rounded to nice ticks | No | Default: the range of x including zero, rounded to nice ticks. |
xFormat | FormatSpec | 'number' | No | Default 'number'. |
xLabel | string | for the texts | No | Name of the x measure: in tooltips, announcements and the data table header, and drawn under the x axis when set. Default for the texts: the field name in sentence case, or "X". |
y | Accessor<D, number> | — | Yes | Vertical position: a number per row. |
yAxis | TickSpec | 'none' | — | No | — |
yAxisFormat | AxisFormat | `yFormat` | No | Default: |
yDomain | readonly [number, number] | the range of y and the target, including zero, rounded to nice ticks | No | Default: the range of y and the target, including zero, rounded to nice ticks. |
yFormat | FormatSpec | 'number' | No | Default 'number'. |
yLabel | string | the field name, or "Y" | No | As |
Points and the tooltip #
Each drawn row is one point, and its id is the id accessor or the data index. In onSelect, onActiveChange and a tooltip function, point.datum is your row. The pointer activates the point whose centre is nearest, within 24 px, or within the dot radius (the bubble maxRadius with size) plus 6 px when that is larger, so a small bubble drawn over a large one is picked when the pointer is nearer to its centre. The default tooltip sits above the bubble and shows the name, then the x measure, the y measure with a swatch in the point's tone, and the size when there is one. The active bubble is drawn solid, with a surface-coloured outline and a ring around it.
Keyboard and screen readers #
The chart is a single tab stop. The arrow keys move from one point to the next and back left to right on screen, then bottom to top, then data order, whatever the order of the rows. Home and End jump to the first and last, Enter or Space selects the active point when the chart has onSelect, and Esc clears it. A chart with no drawn point has no tab stop.
Screen readers get the title and description, then an announcement for each point the keyboard moves to, such as “1 of 16, Alder Court, Estimate $8K, Margin 44%, Hours 40 h”: the position, the name, then each measure with its name and formatted value. A visually hidden data table follows the chart, with one row per data row and a column for the name (when there is a label), x, y and size. dataTable takes false to remove it, or { caption, columns } to set the caption and rename the headers; the default headers can also be translated with the headerName, headerX, headerY and headerSize keys of ChartsProvider messages: headerX, headerY and headerSize are the fallback names when the accessor is a function and no label prop is set (a string field gives its name in sentence case), and headerName names the name column.
The full model is in the accessibility guide.