Line 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

Value scale

Curve

Density

Legend

Legend limit

Palette

Number locale

Lock series selectionKeep zero on the value axisMinimal, for a cardLabel the high and lowSolid lines only

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

Draw values that change along time or another order as lines, such as a temperature, a latency, a price or a portfolio against its benchmark. A line says its slope, so it also reads values far from zero: set includeZero={false} and the line takes the height. Always provide a title, a factual summary, and axis names with units. Series default to brand and neutral lines, told apart by dashes and markers; pass palette="categorical" when color must separate categories, such as buckets, or palette="extended" for a chart with more series than twelve, which adds a second dozen hues, the same twelve a step along the ramp; dashes={false} draws every line solid and leaves the markers to tell the series apart. For monitoring, xScale="time" places rows by data[].time, ticks on round times and breaks a line where sampling stops, or past breakAfter, such as 4 days for closes on trading days; references draw thresholds and target bands, and mark events and periods on the x axis; a comparison series, such as a benchmark, draws quieter, and difference shades the lead between two lines; curve="step" holds values sampled on change; yScale="log" spans orders of magnitude. In a dashboard card, density="compact" keeps the plot, legend and floating values; for a trend on a card, minimal leaves the marks alone and extremes labels the period's high and low. Pass data as an immutable array that the caller owns.

Don't mix units on one axis. Use separate charts instead.
Don't draw parts of a whole as lines, such as tokens by kind. Use AreaChart or BarChart with stacked, which shows their total.
Don't plot one measure against another here. Use ScatterChart, one point per item.
Don't put more than seven series on one chart where you can choose: keep the largest, sum the rest as Other, or split the chart. A monitoring view that must compare more, such as tokens per project, keeps every line on the plot, takes the twelve categorical colors, or the twenty-four of palette="extended" when there are more than twelve, and folds the legend with legendLimit.
Don't turn dashes off to unclutter a crowded plot: past 40 points the plot already drops its markers to do that, and a chart drawn solid keeps them, which adds ink. Turn them off for a line style; split the chart when the plot is crowded.
Don't replace missing values with 0. Pass null instead: the chart treats null, undefined, NaN, and Infinity as missing and doesn't connect lines across them.
Don't expect a second value axis. Put a second unit on a second chart, and values orders of magnitude apart on yScale="log".
Don't expect smoothed curves. Lines are linear or steps, so the chart doesn't invent extremes that weren't measured.
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.
Circle, square, and triangle markers and line patterns tell series apart beyond color. They remain in high contrast mode.
With dashes off the markers carry that difference alone, so a chart drawn solid keeps its markers even past 40 points, where a chart drawn with dashes drops them.
Above 40 points, the plot omits markers to reduce overlap. Legend markers, line patterns, details, and the table remain.
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 { LineChart, type ChartDatum } from '@surflane/ui/chart'

const data: ChartDatum[] = [
  { id: 'day-1', label: 'October 1', values: { workspace: 12, inventory: 8 } },
  {
    id: 'day-2',
    label: 'October 2',
    values: { workspace: 18, inventory: null },
  },
  { id: 'day-3', label: 'October 3', values: { workspace: 14, inventory: 10 } },
]
<LineChart
  title='Pipeline activity'
  description='Workspace records 12, 18 and 14 runs; Inventory has no report on October 2.'
  xLabel='Reporting day'
  yLabel='Pipeline run count'
  unit='runs'
  data={data}
  series={[
    { key: 'workspace', label: 'Workspace' },
    { key: 'inventory', label: 'Inventory' },
  ]}
/>

// Controlled selection: update only when the owner accepts the change.
// hiddenSeries={hidden} onHiddenSeriesChange={setHidden}
// Render loading/error/retry in the owning product before the chart.

Key API

Line 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 a benchmark: muted ink at the quiet line weight, drawn under the others	false
`series[].planOf`	the key of the series this one plans, such as a target beside its actual: its color and marker, dashed, at the quiet line weight and under it, while the series it plans stays solid	—
`includeZero`	keeps 0 on the value axis; turn it off for values far from zero, such as prices, so the line takes the height	true
`yScale`	linear \| log: log spans orders of magnitude; zero and negative values stay off the plot and in the table	linear
`curve`	linear \| step: step holds each value until the next	linear
`breakAfter`	on a time axis, the longest wait between rows a line runs across, in ms; past it the line breaks. For closes on trading days, 4 days carries a line over weekends and a holiday; a missing value still breaks it	twice the usual interval
`dashes`	false draws every line solid and leaves the markers to tell the series apart; a plan keeps its dash, which is what makes it a plan	true
`difference`	{series, against, above, below}: shades between two series in the trend-up color where series is above and trend-down where it is below; the legend names both sides and inspecting a row says the side and the size	—
`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), ticks on round times and breaks the line across a gap of more than twice the usual interval	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 dashes and markers, twelve hues for categories, or twenty-four, the same twelve a step along the ramp, for more series than twelve; the dashes and markers step once past every twelve, so two series a dozen apart never share their color, dash and shape at once	neutral
`--surf-chart-line-width`	token: a series line's weight, which the legend's swatches follow; set it on :root for every chart, or on one chart	2
`--surf-chart-line-quiet-ratio`	token: the share of that weight a comparison or a plan draws at; 1 gives every line on the plot the same weight	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='line' 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.