On this page

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 #

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

Job costs, plan vs actual
View of Job costs, plan vs actual
Job costs, plan vs actual
CategoryPlanActualDifference
Labor$640$1,060+$420
Materials$820$760−$60
Equipment$300$300On plan
Permits$150$190+$40

Revenue with good="up": over plan is the good news here. onSelect makes the rows selectable, so this example is a client component.

Revenue by region, plan vs actual
View of Revenue by region, plan vs actual

Props #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
actualAccessor<D, number>—Yes

Actual value: the solid bar.

animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

barSizenumber8No

Thickness of each of the two bars in px. Default 8.

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.

deltaWidthnumber80No

Width of the delta column inside valueWidth, in px. Default 80.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
dividersbooleantrueNo

Thin rules between rows. Default true.

domainreadonly [number, number]zero to the largest plan or actualNo

Value domain. Default: zero to the largest plan or actual.

emptyReactNode"No data"No

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

formatFormatSpec'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'.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

idAccessor<D, Id>the data indexNo

Row id passed to onSelect and onActiveChange. 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>—Yes

Row name.

labelWidthnumber240No

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

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.

onPlanLabelstring"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; point.datum is the row from data.

planAccessor<D, number>—Yes

Planned or estimated value: the hatched bar.

rowHeightnumber56No

Row height in the columns layout; stacked rows add room for the text line. Default 56.

showValuesbooleantrueNo

Show the "$640 → $1,060 +$420" columns. Default true.

styleCSSProperties—No—
sublabelAccessor<D, string>—No

Optional muted second line under the name.

titlestring—No

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

tolerancenumber0No

A difference at or below this counts as on plan. Default 0.

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.

valueWidthnumber220No

Width of the value columns (change and delta) in px. Default 220.

widthnumber—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.