Charts
BarChart
One value per category or period, drawn as bars. BarChart takes your rows, the field for the x axis and the field for the value, and handles the scale, the tooltip, the keyboard and the screen reader.
When to use it #
Use BarChart to compare a single measure across a few categories (orders by region) or to show it over equally spaced periods (margin by week). Put the measure on y, set format once for the axis, the tooltip and the data table, and pass domain when a zero baseline would flatten the differences. For several series that share an x axis, LineChart usually reads better; for a ranked list with long labels, use RankedBars.
Import #
npm i tally-chartsimport { BarChart } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
Props stay serializable here, so the chart renders in a server component. domain keeps the bars from starting at zero, and format="percent" writes the axis and the tooltip.
| Week | Margin |
|---|---|
| W1 | 31.2% |
| W2 | 32.8% |
| W3 | 33.5% |
| W4 | 32.1% |
| W5 | 34.0% |
| W6 | 35.4% |
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'bar-chart/margin-by-week',
title: 'Margin by week, last 6 weeks',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', margin: 31.2 },
{ week: 'W2', margin: 32.8 },
{ week: 'W3', margin: 33.5 },
{ week: 'W4', margin: 32.1 },
{ week: 'W5', margin: 34.0 },
{ week: 'W6', margin: 35.4 },
]
// Props stay serializable (no functions): the page is a server component.
export default function MarginByWeek() {
return (
<BarChart
data={weeks}
x="week"
y="margin"
domain={[26, 40]}
format="percent"
height={240}
title={meta.title}
description="Margin rose from 31.2% to 35.4% over six weeks."
/>
)
}
With onSelect the chart needs a client component, because the handler is a function. Click a bar, or focus the chart and press Enter.
'use client'
import { useState } from 'react'
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'bar-chart/selectable',
title: 'Orders by region, select a bar',
rscSafe: false,
} satisfies ExampleMeta
const regions = [
{ region: 'North', orders: 1280 },
{ region: 'South', orders: 940 },
{ region: 'East', orders: 1115 },
{ region: 'West', orders: 1460 },
]
// onSelect is a function prop, so this example needs a client component.
export default function Selectable() {
const [selected, setSelected] = useState<string | null>(null)
return (
<>
<BarChart
data={regions}
x="region"
y="orders"
format="number"
height={240}
title={meta.title}
description="West has the most orders, South the fewest."
onSelect={(id) => setSelected(String(id))}
/>
<p aria-live="polite">{selected === null ? 'Nothing selected.' : `Selected: ${selected}`}</p>
</>
)
}
valueLabel="max" labels only the highest bar (the first, on a tie), and valueLabelVariant="pill" draws the label on a filled pill. The pill sits above the bar. BarChart's default top margin of 24 fits it; a Chart needs margin.top of at least 24.
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'bar-chart/peak-week',
title: 'Orders by week, peak labelled',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', orders: 120 },
{ week: 'W2', orders: 142 },
{ week: 'W3', orders: 188 },
{ week: 'W4', orders: 161 },
{ week: 'W5', orders: 133 },
{ week: 'W6', orders: 149 },
]
// Props stay serializable (no functions): the page is a server component.
export default function PeakWeek() {
return (
<BarChart
data={weeks}
x="week"
y="orders"
valueLabel="max"
valueLabelVariant="pill"
height={220}
title={meta.title}
description="Orders peaked at 188 in week 3."
/>
)
}
x is the category and y the value in both orientations: orientation="horizontal" only puts the categories on the left.
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. |
Keyboard and screen readers #
The chart is a single tab stop. Tabbing in shows the first bar with its tooltip and announces it. Arrow keys move between bars, Home and End jump to the first and last, Enter or Space selects the active bar when the chart has onSelect, and Esc clears the active bar. Esc is only consumed when a bar is active, so an enclosing dialog still closes.
Screen readers get the chart title and description, then an announcement for each bar the keyboard moves to, in the form “1 of 12, Jul 6, 37.5%”: the position, the label and the formatted value. A visually hidden data table with every value follows the chart, so browse mode can read it row by row.
The full model is in the accessibility guide.