On this page

Start

Getting started

Install tally-charts, load its theme once and render a chart from a few rows of data. It takes about a minute.

Install #

Terminal
npm i tally-charts

Like React, the package reads process.env.NODE_ENV to turn development warnings on, so it expects a bundler that defines it (Vite, webpack, Next.js and esbuild with define all do).

Import the theme #

app/layout.tsx
import 'tally-charts/theme.css'

Import the stylesheet once, near the root of your app. It defines the --ch-* design tokens that every chart reads for colors, type and spacing. Light and dark both work out of the box: charts follow the system setting, and a data-ch-theme="light" or data-ch-theme="dark" attribute on any ancestor forces one.

Your first chart #

Revenue by month, first half
View of Revenue by month, first half
Revenue by month, first half
MonthRevenue
Jan118
Feb126
Mar141
Apr137
May152
Jun164

data is an array of plain objects, x and y name the keys to read. The props are serializable, so the same code works in a Server Component.

Name every chart #

If the page already has a visible heading, point the chart at it instead of repeating the text:

<h2 id="margin-heading">Margin by week</h2>
<BarChart aria-labelledby="margin-heading" data={weeks} x="week" y="margin" />

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.

aspectRationumber—No

width / height. Used when height is not set.

axisTickSpec | 'none''ends'No

Category axis ticks, or 'none'. Default 'ends'.

axisFormatAxisFormatthe category itselfNo

Category axis labels: a function of the category. Number presets and date formats don't apply to categories and are ignored with a development warning. Default: the category itself.

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]—No

Value domain. Inferred from the data (including zero) when omitted.

emptyReactNode"No data"No

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

fillPerItem<D, Fill>history 'hatch-fade', last bar 'solid'No

Default: history 'hatch-fade', last bar 'solid'.

formatFormatSpec'number'No

Format for tooltips, announcements and the data table. Default 'number'.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

idAccessor<D, Id>—No—
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>`x`No

Category label for tooltips, announcements and the data table. Defaults to x.

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.

orientation'vertical' | 'horizontal''vertical'No

Default 'vertical'.

paddingnumber0.35No

Inner band padding, 0–1. Default 0.35.

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

A target value, 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.

valueFormatFormatSpec`format`No

Format for value labels. Defaults to format.

valueLabel'last' | 'all' | 'max' | 'none''last'No

Which bars get a value label: 'max' is the highest one. Default 'last'.

valueLabelVariant'text' | 'pill''text'No

'pill' draws value labels on a filled rounded rectangle. On the tallest bar it sits in the top margin, which fits at the default margin.top of 24; a smaller one clips it. Default 'text'.

widthnumber—No

Fixed width in px; turns off container measuring.

xAccessor<D, string | number>—Yes

Category field: the band axis in both orientations.

yAccessor<D, number>—Yes

Value field.

Next steps #

Browse the LineChart page for trends, forecasts and targets. Composition shows how to build your own chart from Chart and its building blocks, Small pieces covers Stat, Meter, Legend and the other HTML pieces, and Hooks and providers covers locale, currency and custom marks. Every chart has its own page in the sidebar.