Charts
ComparisonBars
Plan against actual, one row per item. The plan is a hatched bar, the actual is a solid bar, and the difference is written next to them and colored by whether it is good news.
When to use it #
Use ComparisonBars for budgets, estimates, quotas or targets, where each row has an expected value and a real one: job costs, hours, revenue by region. Set good to say which direction is good news. good="down" (the default) suits costs and hours, where under plan is good. good="up" suits revenue, where over plan is good. Rows within tolerance of the plan read “On plan” (change the text with onPlanLabel), and the part of an overrun beyond the plan is drawn apart from the solid bar. For a plain ranking without a plan, use RankedBars.
Import #
npm i tally-chartsimport { ComparisonBars } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
Costs with good="down": Labor and Permits are over plan, so their deltas are the bad news, and Materials, under plan, is the good news.
| Category | Plan | Actual | Difference |
|---|---|---|---|
| Labor | $640 | $1,060 | +$420 |
| Materials | $820 | $760 | −$60 |
| Equipment | $300 | $300 | On plan |
| Permits | $150 | $190 | +$40 |
import { ComparisonBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'comparison-bars/job-costs',
title: 'Job costs, plan vs actual',
rscSafe: true,
} satisfies ExampleMeta
const costs = [
{ category: 'Labor', plan: 640, actual: 1060 },
{ category: 'Materials', plan: 820, actual: 760 },
{ category: 'Equipment', plan: 300, actual: 300 },
{ category: 'Permits', plan: 150, actual: 190 },
]
// Props stay serializable (no functions): the page is a server component. `initialWidth` is the
// width the first render assumes, so a server-rendered page doesn't change layout after hydration.
export default function JobCosts() {
return (
<ComparisonBars
data={costs}
label="category"
plan="plan"
actual="actual"
good="down"
format="currency"
initialWidth={640}
title={meta.title}
description="Labor ran $420 over plan and permits $40 over. Materials came in $60 under, and equipment was on plan."
/>
)
}
Revenue with good="up": over plan is the good news here. onSelect makes the rows selectable, so this example is a client component.
'use client'
import { useState } from 'react'
import { ComparisonBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'comparison-bars/revenue-by-region',
title: 'Revenue by region, plan vs actual',
rscSafe: false,
} satisfies ExampleMeta
const regions = [
{ region: 'North', plan: 48000, actual: 52400 },
{ region: 'South', plan: 36000, actual: 33200 },
{ region: 'East', plan: 41000, actual: 41000 },
{ region: 'West', plan: 52000, actual: 58900 },
]
// onSelect is a function prop, so this example needs a client component.
export default function RevenueByRegion() {
const [selected, setSelected] = useState<string | null>(null)
return (
<>
<ComparisonBars
data={regions}
label="region"
plan="plan"
actual="actual"
id="region"
good="up"
format="currency"
title={meta.title}
description="West beat its plan by $6,900 and North by $4,400. South fell $2,800 short, and East hit its plan."
onSelect={(id) => setSelected(String(id))}
/>
<p aria-live="polite">{selected === null ? 'Nothing selected.' : `Selected: ${selected}`}</p>
</>
)
}
Props #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | Id | null | — | No | — |
actual | Accessor<D, number> | — | Yes | Actual value: the solid bar. |
animate | boolean | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
barSize | number | 8 | No | Thickness of each of the two bars in px. Default 8. |
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: |
deltaWidth | number | 80 | No | Width of the delta column inside |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
dividers | boolean | true | No | Thin rules between rows. Default true. |
domain | readonly [number, number] | zero to the largest plan or actual | No | Value domain. Default: zero to the largest plan or actual. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
format | FormatSpec | 'number' | No | Default 'number'. |
good | 'up' | 'down' | 'down' | No | Which direction of actual against plan is good news: 'down' (under plan, for costs and hours) or 'up' (over plan, for revenue-like rows). Default 'down'. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | the data index | No | Row id passed to onSelect and onActiveChange. 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> | — | Yes | Row name. |
labelWidth | number | 240 | No | Width of the label column in px, in the columns layout. Default 240. |
layout | 'auto' | 'columns' | 'stacked' | 'auto' | No | 'columns': label, bars and values side by side. 'stacked': the label and the values in a block of up to two lines above bars that span the full width. 'auto' stacks when the bars would get less than 120px between the columns. Default 'auto'. |
margin | Partial<Margin> | — | No | — |
onActiveChange | (id: Id | null, point: ChartPoint<D> | null) => void | — | No | Called with the new active id, and its point; |
onPlanLabel | string | "On plan" | No | Text for rows on plan. Default "On plan". |
onSelect | (id: Id, point: ChartPoint<D>) => void | — | No | Called on click, Enter or Space; |
plan | Accessor<D, number> | — | Yes | Planned or estimated value: the hatched bar. |
rowHeight | number | 56 | No | Row height in the columns layout; stacked rows add room for the text line. Default 56. |
showValues | boolean | true | No | Show the "$640 → $1,060 +$420" columns. Default true. |
style | CSSProperties | — | No | — |
sublabel | Accessor<D, string> | — | No | Optional muted second line under the name. |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tolerance | number | 0 | No | A difference at or below this counts as on plan. Default 0. |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus: |
valueWidth | number | 220 | No | Width of the value columns (change and delta) in px. Default 220. |
width | number | — | No | Fixed width in px; turns off container measuring. |
Keyboard and screen readers #
The chart is a single tab stop. Tabbing in shows the first row with its tooltip and announces it. Arrow keys move between rows, Home and End jump to the first and last, Enter or Space selects the active row when the chart has onSelect, and Esc clears the active row. Esc is only consumed when a row is active, so an enclosing dialog still closes.
Screen readers get the chart title and description, then an announcement for each row the keyboard moves to, in the form “1 of 6, Labor, plan $640, actual $1,060, +$420”: the position, the label, both values and the difference. The values and the delta are also in a visually hidden data table after the chart.
ComparisonBars picks its layout from the measured width: columns when the bars get at least 120 px between the label and the values, stacked rows otherwise. On a server-rendered page a narrow screen first renders columns at the 640 px default and switches to stacked after hydration. To avoid the jump, pass initialWidth or an explicit layout.
The full model is in the accessibility guide.