# Line Chart

Line chart for trends over time: smooth lines (straight on request) and stepped lines, comparisons, bands, forecasts and thresholds, with tooltip, keyboard navigation and a data table.

- Category: Charts
- Page: https://wunderui.com/components/line-chart
- Tier: Core and Pro

## Install

Line Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { LineChart, LineChartBand, LineChartProps, LineChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { LineChart } from "@wunderui/react/charts"

const data = [
  { month: "Jan", revenue: 32000 },
  { month: "Feb", revenue: 41000 },
  { month: "Mar", revenue: 38000 },
  { month: "Apr", revenue: 47000 },
]

export function RevenueTrend() {
  return <LineChart data={data} index="month" series={[{ key: "revenue", label: "Revenue" }]} label="Revenue" />
}
```

Expected result: You see one line over a grid that starts at 0, with the months below it. Hovering the plot shows a tooltip, and the arrow keys walk the points.

## When to use

### Use Line Chart for

- A trend over time with one to five series
- This period against the previous one, a target or a forecast
- Prices and indicators with many points
- A threshold or a band the line should be read against

### Use something else

- [Bar Chart](https://wunderui.com/components/bar-chart) for separate categories or a few periods
- [Area Chart](https://wunderui.com/components/area-chart) for volumes, where the filled area carries the message
- [Sparkline](https://wunderui.com/components/sparkline) for a trend without axes inside a tile or a table
- [Stacked Chart](https://wunderui.com/components/stacked-chart) for the parts of a total over time

## Keyboard

The plot is focusable, so the chart works without a pointer.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous point. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last point. |
| `Shift+ArrowRight` or `Shift+ArrowLeft` | Extends a selected range from the point you started on. A range is only selected when `onSelectedRangeChange` is set. |
| `Escape` | Clears the active point and the selected range. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

What the chart does on its own and what the page decides.

- **Variants set the look:** The variant picks the curve, stroke and layers (bands, markers, a threshold, a forecast). Curve and stroke width override what a variant sets.
- **Gaps:** A missing or non-numeric value leaves a gap in the line, not a line down to zero. Dashed series (a forecast, the previous period) are drawn dashed.
- **Scale:** The grid has seven lines from 0. You can change intervals, domain and ticks, drop zero to fit the data, or use the log variant for whole decades.
- **Headline value:** Pass the active index out and the value of that point to the ChartCard: the headline counts to each new value while the pointer slides.
- **Texture and ghost trail:** A texture replaces the grid, never adds to it, and only one decorative layer goes on a chart (no texture with a pattern or a glow). The ghost trail draws last period faint behind the current one and morphs with the data.
- **Hero variants:** glow-line is a named hero variant (owner decision, Nov 12 2026): a smooth line with a soft glow in its own colour, ending on a dot. Never a default and never in a dense dashboard; with reduced motion the glow is off.
- **Loading, empty and error:** The chart keeps its size while loading, empty or failed, so the card never changes height. Add a retry handler to show a Try again button on error.
- **Legend:** A ChartCard shows series as badges. With two or more series each badge toggles its series, the last visible one stays on, and a legend of roles can be made static.
- **Data table:** The chart renders its data as a table for screen readers, in plot order. A ChartCard can show that table on screen through a toggle that keeps the card height.
- **Size:** The chart fills the width of its container, and you set the plot height. Text never scales: labels keep their size at every width.

## Motion

The enter sequence and hover follow the library's motion tokens.

- **Draw-in:** Each series is drawn along its path the first time the chart is in view, and again after loading or when new data arrives. You can turn it off.
- **Hover:** The crosshair and the active points glide from point to point instead of jumping.
- **Reduced motion:** With reduced motion the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

## Anatomy

- `LineChart`: Takes the data, the category field and a list of series (key, label, colour, dashed). Curve and stroke width override the variant; one formatter handles tooltip, axis, table and summary.
- `Plot`: The focusable region, a group named by the label. Left and Right walk the points, Home and End jump to the ends, Shift with an arrow or a drag selects a range (with a range handler), Escape clears.
- `Grid and axes`: Seven grid lines from 0 by default, value labels centred on them, category labels below. You can change the scale; the log variant runs on whole decades, and dropping zero fits the data.
- `Series paths`: One path per series, drawn along its path on first view. A missing or non-numeric value leaves a gap, not a line to zero, and dashed series (forecast, previous period) are drawn dashed.
- `Bands and annotations`: Layers only some variants draw: reference, confidence, forecast and indicator bands, the positive-negative threshold, the Today marker, end dots and the high tag.
- `Crosshair and active points`: A dashed crosshair and one ringed point per visible series follow the hovered or focused category, gliding between points. Projection-fade has no crosshair; its cursor sits at the projection index.
- `Tooltip`: The category label (or a custom title), one row per visible series in its colour, and a change chip against the previous point from the first visible series. It is hidden from assistive technology.
- `Loading, empty and error`: Loading shows a muted area skeleton with the shimmer, empty a centred message (also when the data holds no numbers), and error a message with a Try again button when a retry handler is set.
- `Data table and live region`: A screen-reader table of every category and series, and a polite live region that reads the point the keyboard is on.

## Best practices

### When to use

- Use LineChart for change along an ordered axis, usually time, when slope matters more than exact amounts. Use BarChart to compare categories and AreaChart when the volume matters.

### Do

- Stay at five series or fewer. Beyond that lines cross constantly and hues can't be told apart; let people switch series off in the ChartCard legend or split into two charts.
- Separate series by more than colour: dash forecasts and comparisons (the comparison and year-over-year variants do it for every later series), so the chart works for people who can't tell hues apart.
- Keep the value axis at 0 unless the values sit in a narrow band. For prices or temperatures drop zero and say so in the card description, so a cropped baseline isn't read as a collapse.
- Annotate with props instead of drawing on top: forecastFrom (dotted forecast after a labelled divider, legend via forecastLegendItems), trendline, events (icon buttons with a tooltip), range (grey stripes behind the line) and rangeBand (a faded band from a lower and an upper field; the tooltip shows the span).

### Don't

- Don't join categories that have no order, such as plans or regions. The line implies a trend between them; use BarChart.
- Don't leave data states to guesswork. Set loading while fetching and error with a retry handler on failure; an empty data array already shows the empty message.

## API reference

### LineChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per category / point. |
| index* | string |  | Field holding the category label (x axis; y axis for horizontal bars). |
| series* | readonly ChartSeries[] |  | The series to draw, in order. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  | Enter sequence (draw, wipe, grow) on scroll into view, after loading and on new data. Default true; off with reduced motion. |
| animationKey | string \| number |  | Change it to play the enter sequence again (e.g. `useChartReload().version`). New `data` replays it by itself. |
| aspectRatio | number |  | Width ÷ height when `height` is not set. Default 2.6. |
| axisFormatter | ChartValueFormatter |  | Value-axis labels; defaults to `valueFormatter`. |
| bands | readonly LineChartBand[] |  | `confidence-band`, `forecast-fan`: bands between two fields, drawn behind the lines. |
| categoryAxis | boolean |  | Category-axis labels (default true). |
| categoryFormatter | (label: string) => string |  | Shortens category labels on the axis, e.g. "Mar 12" → "Mar"; tooltip and pill keep the full label. |
| categoryTicks | readonly string[] |  | Only these category labels are shown on the axis (the rest stay hoverable). |
| className | string |  | Extra classes for the root element of the chart. |
| curve | "linear" \| "smooth" \| "step" |  | Override the variant's curve: straight, monotone smooth or step. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| defaultSelectedRange | ChartRange \| null |  | The range that is selected at first, for an uncontrolled chart. |
| description | string |  | Screen-reader summary; generated from the data when omitted. |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| events | readonly ChartEvent[] |  | Event markers: a dotted line over the plot and a round icon button above it; several at one index get a counter badge. |
| forecastFrom | number |  | Index of the first forecast point: a dashed divider with "Forecast from <category>", the line dotted from the last actual point on and ending on a dot. `forecast-fan`: index of "today" (default: the first point of the second series). |
| forecastLabel | string |  | Label of the forecast divider. Default "Forecast from <category>"; `forecast-fan`: "Today". |
| ghost | string \| ChartGhost |  | The previous period as a faint ghost behind one series: a field name, or `{ key, label, series }`. Lines get a faint line in the series colour. The tooltip lists it under its series, the table adds a column; give the legend item `ghost: true` for a faint ring. |
| gradientTo | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" | "orange" | `gradient-step`: end colour of the stroke gradient. Default orange. |
| grid | boolean |  | Grid lines (default true). |
| gridFade | boolean |  | The grid fades out towards both ends (default true). |
| gridIntervals | number |  | Number of equal grid intervals. Default: one per 44 px of plot height, capped by the size class (xs 2, sm 3, md 3, lg 4, xl 5). |
| gridStyle | "solid" \| "dashed" |  | Grid lines are dashed 4 / 4 by default; `solid` draws them through. |
| height | number |  | Fixed height of the plot frame in px. Without it the height follows the width (`aspectRatio`, `minHeight`, `maxHeight`): 220 px on a phone, up to 434 px (the plot of the Figma large card) from about 1130 px wide. |
| hiddenSeries | readonly string[] |  | Series keys that are switched off (legend toggle): drawn faded, dimmed in the tooltip. |
| includeZero | boolean |  | The value axis starts at 0 (owner rule, default). `false` fits the data (prices, temperatures). |
| indicatorBand | { lower: number; upper: number } |  | `indicator-band`: the neutral band, e.g. RSI 30–70. |
| label | string |  | Accessible name, e.g. the card title. |
| maxHeight | number |  | Highest height from `aspectRatio`. Default 434. |
| minHeight | number |  | Lowest height from `aspectRatio`. Default 220. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| onSelectedRangeChange | (range: ChartRange \| null) => void |  | Called when a drag across the plot or Shift with an arrow key changes the range, and with `null` when Escape or a click clears it. |
| projectionIndex | number |  | `projection-fade`: where the cursor sits (default: the hovered point, else the middle). |
| range | ChartRangeHighlight |  | A highlighted range of categories with grey stripes behind the marks and an optional label. |
| rangeBand | ChartRangeBand |  | A band around a series from two fields, faded at both ends with its line; the tooltip shows "42k · 38k – 47k". |
| rangeSelectable | boolean |  | Allow selecting a range by dragging or Shift + arrow keys. On when `onSelectedRangeChange` is set. |
| referenceBand | { from: number; to: number; label?: string } |  | `reference-band`: the highlighted category range (indices, inclusive) and its label. |
| resolution | "auto" \| "full" |  | `auto` (default): lines and areas draw at most 1.5 points per pixel (LTTB; hover and tooltip keep every point), and bars on a time axis that would get thinner than they may are gathered into weeks, months … `full` draws every point and eve… |
| selectedRange | ChartRange \| null |  | The selected range as inclusive indices `[from, to]` into `data`, to control it yourself. `null` selects nothing. |
| state | "ready" \| "loading" \| "empty" \| "error" |  | `loading` shows the chart-shaped skeleton, `empty` and `error` a message in the plot. |
| strokeWidth | number |  | Stroke width in px; each variant has its Figma default. |
| texture | "dots" \| "diagonal" \| "grid" |  | `dots`, `diagonal` or `grid`: a quiet background texture in place of the grid lines (never both), in the grid colour and faded at all four edges; the zero line stays. |
| threshold | number | 0 | `positive-negative-line`: the value the line is split at (default 0). |
| thresholdLabel | string |  | Label at the end of the threshold line, e.g. "Target 30k". |
| tooltip | boolean |  | Tooltip on hover / keyboard focus. Default true. |
| tooltipTitle | (datum: ChartDatum, index: number) => React.ReactNode |  | Title line of the tooltip; defaults to the category label. |
| trendline | boolean \| readonly string[] |  | Linear trend (least squares), dotted in a lighter step of the series colour: `true` for every series or a list of series keys. |
| valueAxis | boolean |  | Value-axis labels (default true). Off for compact cards and sparkline-like plots. |
| valueAxisPlacement | "auto" \| "outside" \| "inside" |  | Where the value labels go: `outside` left of the plot, `inside` in the plot above their grid lines (saves the label column on narrow charts). `auto` (default) puts them left of the plot at every size; `inside` is opt-in. |
| valueAxisSide | "left" \| "right" |  | Side of the value axis (vertical charts). `right` is the price axis of trading charts. |
| valueDomain | readonly [number, number] |  | Fix the value domain instead of fitting it to the data (still rounded to nice steps). |
| valueFormatter | ChartValueFormatter |  | Values in tooltip, labels, table and live region. Default: 42000 → "42k". |
| valueTicks | readonly number[] |  | Exact value-axis ticks (ascending), e.g. [0, 10000, … 70000]; replaces the nice-step domain. |
| variant | "basic-line" \| "stroke-line" \| "dashed-line" \| "basic-step" \| "stroke-step" \| "dashed-step" \| "gradient-line" \| "smooth-line" \| "comparison-line" \| "positive-negative-line" \| "reference-band" \| "gradient-step" \| "line-with-markers" \| "confidence-band" \| "forecast-fan" \| "log-scale-line" \| "projection-fade" \| "volatile-price-line" \| "share-lines" \| "indicator-band" \| "year-over-year" \| "multi-line-5" \| "glow-line" | "basic-line" | Figma variant. Default `basic-line`. |
| width | number |  | Fixed width instead of filling and measuring the container. |
| xScale | "band" \| "time" |  | `band` (default): the categories sit side by side in equal bands. `time`: the `index` field holds dates (Date, ms or a string such as "2026-03-01"); points sit at their real distance, the axis picks its tick level (hours → days → weeks → m… |

## Examples

### States

### Forecast

### Trendline

### Event markers

### Range

### Range band

### Background texture

### Ghost trail

### Table view

## In context

### Revenue vs Prior Period

Payments overview: gross volume per day against the previous period, with KPI cards and a range segment.

### Website Visitors

Web analytics: daily visitors with a hover tooltip, a visitors and page views switch, and the top pages.

### Asset Price with Range Tabs

Asset detail: a price line with 1D to 1Y ranges. The line turns red when the range closes lower.

## For AI agents

`get_component("line-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
