Bar chart | Surflane

AvailableRecharts composition

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Compare the same example at each size and density. Switching keeps input values and selection state. Size guidance and comparisons

Chart data

Density

Legend

Legend limit

Palette

Number locale

Lock series selectionStack the seriesMinimal, for a cardLabel the high and low

Pipeline activity

Six sample days. Workspace rises from 12 to 27 runs. Inventory has no measurement on October 3, so the chart leaves a gap there.

Pipeline run count (runs)

Reporting day

Focus the chart and use Left/Right to inspect points. Escape clears details. The data table includes every series.

View data table

All series are visible.

Usage

Compare amounts per period or category as bars, such as runs per day, tokens per day by kind or an allocation against its targets. A bar's length is its amount, so bars always start at zero on a linear axis. Always provide a title, a factual summary, and axis names with units. Series default to brand and neutral fills, told apart by fill patterns; pass palette="categorical" when color must separate categories, such as kinds or buckets, or palette="extended" for a chart with more series than twelve. stacked adds the series into one bar per row, whose top is their total and which the readout names. A plan, such as a target, is a level to reach: an unfilled dashed bar beside its series, outside the stack and its total. With xScale="time", rows sit by data[].time, each bar centered on its own. references draw thresholds and target bands, and mark events and periods on the x axis. In a dashboard card, density="compact" keeps the plot, legend and floating values; minimal leaves the marks alone. Pass data as an immutable array that the caller owns.

Don't draw a long or finely sampled series as bars, such as a day every ten minutes: past a few dozen rows the bars thin out to lines. Use LineChart.
Don't expect bars for values far from zero or orders of magnitude apart: a bar starts at zero, and a log axis has none. Use LineChart, with includeZero={false} or yScale="log".
Don't stack series that don't add up, such as latency per region. Stack only parts of a total, and set the others side by side.
Don't mix units on one axis. Use separate charts instead.
Don't replace missing values with 0. Pass null instead: the chart treats null, undefined, NaN, and Infinity as missing and leaves the bar out, while a 0 is a bar of no length.
Don't rank named values as bars here. Use BarList, which sorts them with their names and values as text.
Don't expect the chart to show loading, error, or retry states. Build them in the product screen.
Don't expect the description prop to be an automatically inferred analysis. It holds the caller's factual summary.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

figure → figcaption(title + summary) + legend toggle buttons + named axes + responsive Recharts ComposedChart + persistent inline value readout + details → Table.Container → full data table

Keyboard and accessibility

Tab reaches the legend buttons, the chart, and the data table toggle.
With the chart focused, Left and Right move between data points.
Enter or Space on a legend button shows or hides its series, and aria-pressed reports whether it's shown. Hidden series stay in the data table.
View data table is a native details element that Enter or Space expands. Long tables scroll on both axes. Each series header names the unit once, and the cells hold full values aligned at the end.
Escape clears the details, and an arrow key shows them again.
Pointer, touch and the arrow keys show the point's values in a box beside it, which turns to whichever side has more room and stays inside the plot. The same values fill the details region below the plot, a polite live region that never covers the marks; the box itself stays out of the accessibility tree.
Fill patterns tell the bars apart beyond color, and the legend draws the same ones. They remain in high contrast mode.
Animation is off by default.
While the chart's room keeps changing, as while a sidebar slides or a window edge is dragged, the plot holds the width it was drawn at, clipped to the chart, and redraws once the room settles. A single change of room draws at once.
Test real assistive technology usability separately after product integration.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

// Needs recharts: npm install recharts
import { BarChart, type ChartDatum } from '@surflane/ui/chart'

const data: ChartDatum[] = [
  { id: 'oct-1', label: 'October 1', values: { prefill: 3.2, decode: 1.1 } },
  { id: 'oct-2', label: 'October 2', values: { prefill: 4.0, decode: 1.4 } },
  { id: 'oct-3', label: 'October 3', values: { prefill: 2.6, decode: null } },
]
<BarChart
  title='Tokens per day'
  description='Prefill leads every day; decode has no report on October 3.'
  xLabel='Day'
  yLabel='Tokens'
  unit='M tokens'
  data={data}
  series={[
    { key: 'prefill', label: 'Prefill' },
    { key: 'decode', label: 'Decode' },
  ]}
  palette='categorical'
  stacked
/>

Key API

Bar chart — common wrapper props
Prop	Contract	Default
`title / description / xLabel / yLabel / unit`	required string labels, a factual summary, and a shared unit	required
`data`	readonly {id, label, values: Record<seriesKey, number \| null \| undefined>}[]; unique non-empty id	required
`series`	readonly {key, label, color?}[]; unique non-empty key; color replaces the palette's for one series	required
`series[].comparison`	a series the others are read against, such as last year's: muted ink, in the legend's order and out of a stack	false
`series[].planOf`	the key of the series this one plans, such as a target beside its actual: a level to reach, not an amount, so an unfilled dashed bar in its color beside it, at the quiet line weight, in the legend's order and out of a stack	—
`stacked`	stacks the series into one bar per row, whose top is their total, which the readout adds; a comparison or a plan is read against the stack, not added to it, so it stands beside it and stays out of the total	false
`height`	finite pixel height, minimum 200 (120 when compact); 'fill' takes the container's height, as in a stretched dashboard panel, and gives the plot what the caption and legend leave, never less than the default	280 / 180 compact
`xScale / data[].time`	category spaces rows evenly by label; time places them by time (ms or Date), each bar centered on its own, and ticks on round times	category
`references`	readonly ({y, label, tone?} \| {from, to, label, tone?} \| {x, label, tone?} \| {xFrom, xTo, label, tone?})[]: threshold lines and bands the value axis reaches, and event lines and periods at a datum id or a time, in neutral, caution or danger. The legend names each with its value or place; inspecting a row names the events and periods at it	[]
`density`	default \| compact: compact keeps the plot, legend and floating values; caption, help and readout stay for assistive technology	default
`minimal`	the marks alone, for a trend on a card: no axes, grid, legend or axis names on screen; the readout, keyboard, references and data table stay, the axis names stay for assistive technology, and the table's disclosure shows only when keyboard focus reaches it	false
`extremes`	labels the highest and lowest value of the first shown series with its value and its row's label, such as a period's high and low	false
`legendPosition / legendLimit`	top \| bottom / how many entries the legend shows, series first, then references and the difference's sides, before folding the rest behind a "+N" popover; auto shows as many as fit one line	top / every series
`palette`	neutral \| categorical \| extended: ink with fill patterns, twelve hues for categories, or twenty-four, the same twelve a step along the ramp, for more series than twelve; the patterns step once past every twelve, so two series a dozen apart never share their color and pattern at once	neutral
`--surf-chart-line-width / --surf-chart-line-quiet-ratio`	tokens: a plan's dashed outline draws at their product, the weight of a plan's line on the other charts	2 / 0.75
`locale / formatValue`	Intl number and date locale, as the number helpers take; pass it when the server renders the chart, so its text matches the browser's / optional finite-value formatter (unit appended)	the runtime's / maximum 2 fractional digits
`hiddenSeries / defaultHiddenSeries / onHiddenSeriesChange`	controlled or uncontrolled hidden keys; callback requests the next keys	uncontrolled / []
`labels`	text the chart shows or announces: missing, empty, noSeries, showAll, keyboardHelp, values, viewTable, table, tableCaption, inspectHint, noRows, legend(title), series(label), moreSeries(count), moreEntries(count), total, high, low	English
`ChartSeriesMark`	{type, index, palette, color, comparison, plan, dashes}: a series' swatch as the legend draws it, for a key of your own; give it type='bar' and the flags of the series it keys	line / neutral / dashed
`ref / className / figure props`	root HTMLElement ref and native figure attributes	optional
`Chart`	deprecated: LineChart, AreaChart and BarChart in one, picked by type='line' \| 'bar' \| 'area', taking every chart's props whether its marks read them or not	—

The table lists the common wrapper's main props. See the package type declarations for the full types.