Charts
RankedBars
A ranked list: one horizontal bar per item, sorted by size, with the label on the left and the value on the right. An optional muted column adds a detail such as a job count.
When to use it #
Use RankedBars for “what is the biggest” questions: overruns by category, hours by technician, top customers. It sorts by the size of the value (sort), can cut the list (limit), and gives long labels a tooltip. By default the bars are solid: fill is 'solid'. Pass fill="hatch" for the look of a plan or a reference, so a list of planned values doesn’t pass for actuals. fill also accepts a function, to hatch only some rows. When each row has both a plan and an actual, use ComparisonBars instead.
Import #
npm i tally-chartsimport { RankedBars } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
No fill prop: the bars are 'solid', the default. tone="loss" colors the bars and the values.
| Category | Amount |
|---|---|
| Labor overruns | $31.2K |
| Material waste | $18.4K |
| Rework | $12.9K |
| Equipment rental | $7.6K |
| Permits | $2.1K |
import { RankedBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'ranked-bars/overruns',
title: 'Cost overruns by category',
rscSafe: true,
} satisfies ExampleMeta
const overruns = [
{ category: 'Labor overruns', amount: 31200 },
{ category: 'Material waste', amount: 18400 },
{ category: 'Rework', amount: 12900 },
{ category: 'Equipment rental', amount: 7600 },
{ category: 'Permits', amount: 2100 },
]
// No `fill` prop: the bars use the default, 'solid'. Props stay serializable (no functions).
export default function Overruns() {
return (
<RankedBars
data={overruns}
label="category"
value="amount"
format="currency-compact"
tone="loss"
title={meta.title}
description="Labor overruns lead at $31.2K, followed by material waste at $18.4K. Permits cost the least, $2.1K."
/>
)
}
fill="hatch" marks the bars as a plan. meta adds the muted “9 jobs” column before the value.
import { RankedBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'ranked-bars/hatch-plan',
title: 'Planned hours by technician',
rscSafe: true,
} satisfies ExampleMeta
const plan = [
{ name: 'Tyler Brooks', hours: 62, jobs: '9 jobs' },
{ name: 'Dana Ortiz', hours: 54, jobs: '8 jobs' },
{ name: 'Sam Patel', hours: 47, jobs: '6 jobs' },
{ name: 'Priya Nair', hours: 31, jobs: '4 jobs' },
]
// fill="hatch" gives the bars the look of a plan or a reference. `meta` adds the muted column.
export default function HatchPlan() {
return (
<RankedBars
data={plan}
label="name"
value="hours"
meta="jobs"
format="hours"
fill="hatch"
title={meta.title}
description="Tyler Brooks is planned for 62 hours across 9 jobs, Priya Nair for 31 hours across 4."
/>
)
}
With onSelect and selectedId, a row can drive something else on the page. Focus the chart and press Enter or Space on a row.
'use client'
import { useState } from 'react'
import { RankedBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'ranked-bars/pick-a-category',
title: 'Overruns by category, pick a row',
rscSafe: false,
} satisfies ExampleMeta
const overruns = [
{ category: 'Labor overruns', amount: 31200 },
{ category: 'Material waste', amount: 18400 },
{ category: 'Rework', amount: 12900 },
{ category: 'Equipment rental', amount: 7600 },
]
// onSelect and selectedId are the pair for a list that filters something else.
export default function PickACategory() {
const [selected, setSelected] = useState<string | number | null>(null)
return (
<>
<RankedBars
data={overruns}
label="category"
value="amount"
id="category"
format="currency-compact"
selectedId={selected}
title={meta.title}
description="Press Enter or Space on a row to select it. Labor overruns lead at $31.2K."
onSelect={(id) => setSelected((current) => (current === id ? null : id))}
/>
<p aria-live="polite">{selected === null ? 'Nothing selected.' : `Selected: ${selected}`}</p>
</>
)
}
Bars show magnitudes, so a negative "lost" amount extends to the right like the others and keeps its sign in the text.
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 |
barSize | number | 12 (inline) or 6 (stacked) | No | Default 12 (inline) or 6 (stacked). |
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] | zero to the largest magnitude | No | Domain of bar lengths. Default: zero to the largest magnitude. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
fill | PerItem<D, Fill> | 'solid' | No | Default 'solid'. Use 'hatch' for a plan or reference look. |
format | FormatSpec | 'number' | No | Default 'number'. |
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 compared with selectedId. 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 | — |
labelWidth | number | — | No | Inline label column width in px (default 140). In the stacked layout, a max label width. |
layout | 'inline' | 'stacked' | 'inline' | No | 'inline': label | bar | value on one line. 'stacked': label and value above a thin bar. Default 'inline'. |
limit | number | — | No | Show only the first rows after sorting. |
margin | Partial<Margin> | — | No | — |
meta | Accessor<D, string> | — | No | Muted text before the value, e.g. "9 jobs". |
metaWidth | number | 64 | No | Meta column width in px. Default 64. |
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; |
rowHeight | number | 40 (inline) or 52 (stacked) | No | Default 40 (inline) or 52 (stacked). |
selectable | PerItem<D, boolean> | true | No | False for rows |
selectedId | Id | null | — | No | The highlighted row. Hover and focus stay separate ( |
selectedTone | Tone | 'loss' | No | Tone of the selected row's bar and value. Default 'loss'. |
sort | 'desc' | 'asc' | 'none' | 'desc' | No | By size of the value, ignoring its sign. Default 'desc'. |
style | CSSProperties | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tone | PerItem<D, Tone> | 'neutral' | No | Default 'neutral'. A non-neutral tone also colors the value text. |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus, so cut labels stay readable: |
track | boolean | true | No | Faint track behind each bar. Default true. |
value | Accessor<D, number> | — | Yes | — |
valueWidth | number | 72 | No | Inline value column width in px. Default 72. |
width | number | — | No | Fixed width in px; turns off container measuring. |
Keyboard and screen readers #
RankedBars is built on Chart, so it follows the same keyboard model as the other charts: the list is a single tab stop, and tabbing in shows the first row with its tooltip and announces it. Arrow keys move between rows (rows are sorted, so “previous” and “next” follow the order on screen), Home and End jump to the first and last row, 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. A row with selectable: false takes focus and a tooltip but Enter skips it.
Screen readers get the chart title and description, then an announcement for each row the keyboard moves to, in the form “1 of 5, Labor overruns, $31.2K”. With meta the detail is added: “1 of 5, Tyler Brooks, $2.6K, 9 jobs”. A visually hidden data table with the label, the value and the details follows the chart. Hatch is only a visual cue, so say in the title or description when a list shows a plan.
The full model is in the accessibility guide.