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 #
npm i tally-chartsLike 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 #
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 #
| Month | Revenue |
|---|---|
| Jan | 118 |
| Feb | 126 |
| Mar | 141 |
| Apr | 137 |
| May | 152 |
| Jun | 164 |
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'getting-started/first-chart',
title: 'Revenue by month, first half',
rscSafe: true,
} satisfies ExampleMeta
const months = [
{ month: 'Jan', revenue: 118 },
{ month: 'Feb', revenue: 126 },
{ month: 'Mar', revenue: 141 },
{ month: 'Apr', revenue: 137 },
{ month: 'May', revenue: 152 },
{ month: 'Jun', revenue: 164 },
]
// Props stay serializable (no functions): the page is a server component.
export default function FirstChart() {
return (
<BarChart
data={months}
x="month"
y="revenue"
height={240}
title={meta.title}
description="Revenue grew from 118k in January to 164k in June."
/>
)
}
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 #
| 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 |
aspectRatio | number | — | No | width / height. Used when |
axis | TickSpec | 'none' | 'ends' | No | Category axis ticks, or 'none'. Default 'ends'. |
axisFormat | AxisFormat | the category itself | No | 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. |
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] | — | No | Value domain. Inferred from the data (including zero) when omitted. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
fill | PerItem<D, Fill> | history 'hatch-fade', last bar 'solid' | No | Default: history 'hatch-fade', last bar 'solid'. |
format | FormatSpec | 'number' | No | Format for tooltips, announcements and the data table. Default 'number'. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | — | No | — |
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> | `x` | No | Category label for tooltips, announcements and the data table. Defaults to |
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; |
orientation | 'vertical' | 'horizontal' | 'vertical' | No | Default 'vertical'. |
padding | number | 0.35 | No | Inner band padding, 0–1. Default 0.35. |
style | CSSProperties | — | No | — |
target | number | { value: number; label?: string } | — | No | A target value, 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: |
valueFormat | FormatSpec | `format` | No | Format for value labels. Defaults to |
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 |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | Accessor<D, string | number> | — | Yes | Category field: the band axis in both orientations. |
y | Accessor<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.