On this page

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 #

Terminal
npm i tally-charts
app/jobs.tsx
import { 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.

Margin by crew hours, one dot per job
View of Margin by crew hours, one dot per job
Margin by crew hours, one dot per job
NameCrew hoursMargin, %
Alder Court4044
Birch Lane5838
Cedar Row4052
Dune House10341
Elm Terrace7935
Fern Hill10346
Grove Flats16033
Hazel Yard16039
Ivy Works23136
Juniper Mill52034
Kestrel Barn7929
Larch Depot13024
Maple Arcade23118
North Quay27127
Orchard Mews36130
Harbor Lofts41012

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.

Margin by job size, bubble area is crew hours
View of Margin by job size, bubble area is crew hours

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.

Margin by job size, both axes fixed
View of Margin by job size, both axes fixed

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.

Margin by job size, with a legend
View of Margin by job size, with a legend

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 #

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—
emptyReactNode"No data"No

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

gridbooleantrueNo

Horizontal grid lines at the y ticks. Default true.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

idAccessor<D, Id>the data indexNo

Point id. Default: the data index.

initialWidthnumber640No

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

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.

labelAccessor<D, string>—No

Item name for tooltips, announcements and the data table.

marginPartial<Margin>—No—
maxRadiusnumber18No

Radius in px of the bubble with the largest size. Default 18.

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.

radiusnumber5No

Dot radius in px when size is not set. Default 5.

sizeAccessor<D, number>—No

A third measure drawn as the area of each point (a bubble chart). Without it every point is a dot of radius.

sizeFormatFormatSpec'number'No

Default 'number'.

sizeLabelstringthe field name, or "Size"No

As xLabel, for size; never drawn. Default: the field name, or "Size".

styleCSSProperties—No—
targetnumber | { value: number; label?: string }—No

A horizontal target line on y, optionally with a label.

titlestring—No

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

tonePerItem<D, Tone>'accent'No

Default 'accent'.

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, number>—Yes

Horizontal position: a number per row.

xAxisTickSpec | 'none'—No—
xAxisFormatAxisFormat`xFormat`No

Default: xFormat.

xDomainreadonly [number, number]the range of x including zero, rounded to nice ticksNo

Default: the range of x including zero, rounded to nice ticks.

xFormatFormatSpec'number'No

Default 'number'.

xLabelstringfor the textsNo

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".

yAccessor<D, number>—Yes

Vertical position: a number per row.

yAxisTickSpec | 'none'—No—
yAxisFormatAxisFormat`yFormat`No

Default: yFormat.

yDomainreadonly [number, number]the range of y and the target, including zero, rounded to nice ticksNo

Default: the range of y and the target, including zero, rounded to nice ticks.

yFormatFormatSpec'number'No

Default 'number'.

yLabelstringthe field name, or "Y"No

As xLabel, for y; drawn above the y axis when set. Default: the field name, or "Y".

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.