BarList

PreviewSVGPublishes selection

Ranks categories as labelled rows with a bar under each, for top-N lists where labels must stay readable.

Revenue by region

Last 15 days · change vs the 15 days before

Revenue by region
Region	Revenue	Change
North America	$87,028.28	+19.3%
Europe	$53,379.58	+5.4%
Asia Pacific	$36,081.04	+10.5%
Latin America	$17,250.83	+18.4%
Middle East & Africa	$10,609.60	+25.2%

variant

sort

deltalimit 3select

<BarList
  data={regionRevenue}
  category="region"
  value="revenue"
  delta="change"
  select
/>

Installation

BarList is exported from @quartile/react, alongside every other chart and component.

git clone https://github.com/zinnoberHaus/quartile

Not on npm yet: build the package from the clone as described in Installation. The preview API may change before publication.

Usage

Raw rows are aggregated per category: summed with a value, counted without one.

import { BarList } from '@quartile/react';

// orders: { region: 'Europe', amount: 128.5 }, …
type Order = { region: string; amount: number };

export function TopRegions({ orders }: { orders: Order[] }) {
  return <BarList data={orders} category="region" value="amount" limit={5} select />;
}

With select, each row is a button that toggles its category in the nearest <Selection>. See Linked selections.

Props

PropTypeDefaultDescription

datarequiredDataInput<R>—Rows to rank, or a dataset with a schema attached. Raw rows are aggregated per category.

categoryrequiredkeyof R & string—Field whose values become the rows of the list.

valuekeyof R & string—Measure to aggregate. Omit it to count rows per category.

aggregate'sum' | 'count' | 'mean'Aggregatevalue ? 'sum' : 'count'How rows sharing a category combine. Defaults to sum with a value, count without.

preparedbooleanfalseOne already-aggregated numeric value per distinct, typed category. Skips raw-row grouping.

sort'desc' | 'asc' | 'none'SortOrder'desc'Ranking order. Defaults to descending.

limitnumber—Shows at most this many rows; the rest are summarized in a footer line.

formatFormatter—Formats values. Defaults to compact currency, integers for counts, else the field's format.

deltakeyof R & string—Field holding each row's change as a ratio (0.048 → +4.8%), shown after the value.

invertDeltabooleanfalseTreats a fall in the delta as good (e.g. refunds), flipping its color.

variant'bar' | 'fill''bar'bar: label and value on one line with a thin bar under them. fill: a compact row with the bar drawn as a soft fill behind the label.

selectbooleanfalseClicking a row (or Enter on it) toggles its category in the nearest Selection.

idstring—Publisher id for the selection. Defaults to a generated id.

selectionstring | false—Selection to read from and publish to. Defaults to the nearest; false opts out.

onSelect(predicate: Predicate | null) => void—Called after a toggle with the new predicate for category (or null).

Frame and state props shared with the charts (11) · ChartBaseProps, ChartStateProps

PropTypeDefaultDescription

heightnumber—Plot height in px. Width always fills the container.

classNamestring——

styleCSSProperties——

aria-labelstring—Accessible name. A summary of the data is generated and rendered as hidden text inside the figure.

view'chart' | 'table'—table renders the same data as a table, with the same formats, at the chart's size. Large lazy tables expose a data-view control rather than mounting every hidden row.

tooltipNotestring—Plain-text context shown with tooltips and included in the accessible chart description.

loadingboolean | string—Shows the loading state at the chart's size, so the layout never jumps.

errorboolean | string | Error | null—Shows the error state. A string or Error becomes the message.

errorCodestring—Shown in the error state; copyable for support.

onRetry() => void——

empty{ title?: string; description?: string; action?: ReactNode }—Title and description for the empty state. Shown when there are no rows.

Accessibility

Keyboard

With select, rows are buttons: Tab to the list, arrow keys between rows, Home and End to jump, Enter or Space to toggle. Without it, the list is static text.

Screen readers

A summary names the item count and the highest and lowest rows with their values.

Table fallback

Screen readers always get a table of the plotted values with the same formats. view="table" shows it at the chart's size.

Report an issueBuilt Oct 21, 2026