# Area Chart

Area chart for volumes over time: gradients, steps, ranges, a horizon graph, differences and target lines.

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

## Install

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

## Import

```tsx
import { AreaChart, AreaChartProps, AreaChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

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

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

Expected result: You should see one filled area over a grid that starts at 0, with the months below. Hovering shows a crosshair and a tooltip.

## When to use

### Use Area Chart for

- Volumes over time, where the filled area carries the message
- A total made of overlapping series (requests, sessions)
- A band around a value (a range of temperatures), or the gap between two series
- Several signals stacked as horizon rows

### Use something else

- [Line Chart](https://wunderui.com/components/line-chart) for exact values and many series that would hide each other
- [Stacked Chart](https://wunderui.com/components/stacked-chart) for the parts of a total, stacked on top of each other
- [River Chart](https://wunderui.com/components/river-chart) for a mix that changes over time, centred on a baseline
- [Sparkline](https://wunderui.com/components/sparkline) for a small trend without axes

## 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 fill:** The variant picks the fill, the curve (smooth or step) and the layers (band, target line, difference, threshold). A separate curve setting overrides the outline.
- **Order:** Overlapping series are drawn in series order, so the first one sits at the back. Put the largest first.
- **Baseline:** Areas are clipped to the plot and never draw below the baseline, even on a smooth curve.
- **Horizon graph:** The horizon graph gives each series its own row and folds values into bands of deepening shade: positive in the series colour, negative in red.
- **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-area is a named hero variant: the gradient fill under a glowing outline that ends 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 it loads, is empty or fails, so the card never jumps. Loading shows a skeleton; error adds a Try again button when a retry handler is set.
- **Legend:** A ChartCard shows series as badges. With two or more series each badge switches its series off, the last visible one stays on, and a legend of roles can be made static.
- **Data table:** The chart also 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 its container's width; you set the plot height. Text never scales: labels keep their size at every width.

## Motion

The enter sequence and the hover follow the motion tokens of the library.

- **Wipe:** Areas wipe in from the left and outlines draw along their path the first time the chart is in view, and again after loading or when new data arrives.
- **Hover:** The crosshair and the ringed points glide from point to point. The horizon graph has no crosshair.
- **Reduced motion:** With reduced motion on, the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

## Anatomy

- `AreaChart`: Takes data, an index and series. You can pick smooth, straight or step outlines, change the fill opacity, and mark series that skip the fill or the outline.
- `Plot`: The focusable region. Arrow keys walk the points, Shift with an arrow or a drag selects a range, Escape clears it, and hover shows a crosshair and one point per series (not on the horizon graph).
- `Grid and axes`: Grid lines from 0 and the same axis rules as other cartesian charts. Areas are clipped to the plot and never draw below the baseline, even on smooth curves.
- `Areas and outlines`: A fill per series (solid, gradient, reversed gradient or light tint) with a thin outline on top. Overlapping series draw in order, so the first sits at the back.
- `Horizon rows`: The horizon layout: each series gets its own row and values fold into bands of deepening shade, positive in the series colour and negative in red.
- `Range band and target`: The range band between lower and upper values, the split fill and threshold label of the positive-negative area, and the dashed target series of the target-line area.
- `Tooltip`: Category title and one row per visible series, with the change against the previous point on the first series.
- `Loading, empty and error`: Loading shows a muted skeleton shaped like the data; empty and error replace the plot with a message.
- `Data table and live region`: The data as a screen-reader table with a live region for the active point.

## Best practices

### When to use

- Use AreaChart when the size of the total matters, such as traffic or balance over time. Use LineChart to compare several series, because filled areas hide each other.

### Do

- Overlap at most two series, and give the back one the lighter fill. A third filled area covers the others and makes the lower values unreadable.
- For positive and negative values use the positive-negative area with a threshold, not a single colour. The split at the baseline shows which side the value is on without reading the axis.
- Use the horizon graph when many series share a short row height, for example 12 services in one card. Mention the fold count in the description, since the bands are not on a shared scale.
- Annotate with props instead of drawing on top: forecastFrom (striped forecast fill after a labelled divider), trendline, events (icon buttons with a tooltip), range={{ from, to, label }} (grey stripes behind the area) and rangeBand (a faded band around a series).

### Don't

- Don't use a gradient fill to encode data. The fade is decoration; the outline and the tooltip carry the value.
- Don't stack unrelated series in one plot. For parts of a whole use StackedChart, whose stacking is explicit, instead of areas that merely overlap.

## API reference

### AreaChart

| 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`. |
| 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. |
| fillOnly | readonly string[] |  | Series drawn as a fill only (no outline). |
| fillOpacity | number |  | Opacity of solid fills / top of gradient fills (0…1); each variant has its default. |
| forecastFrom | number |  | Index of the first forecast category. From there a dashed divider with a label ("Forecast from Oct"); lines turn dotted and end on a dot, areas fill with stripes, bars are striped with a rim in the series colour. |
| forecastLabel | string |  | Label of the forecast divider. Default "Forecast from <category>" (on small charts "Forecast"). |
| ghost | string \| ChartGhost |  | The previous period as a faint ghost behind one series: a field name, or `{ key, label, series }`. Areas get a faint line and a whisper of fill. The tooltip lists it under its series, the table adds a column; give the legend item `ghost: true` for a faint ring. |
| 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. |
| horizonBands | number | 2 | `horizon-graph`: number of folded bands per row (default 2). |
| includeZero | boolean |  | The value axis starts at 0 (owner rule, default). `false` fits the data (prices, temperatures). |
| label | string |  | Accessible name, e.g. the card title. |
| lineOnly | readonly string[] |  | Series drawn as a line only (no fill), e.g. a benchmark. |
| 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. |
| pattern | ChartPattern \| ChartPattern[] |  | One pattern form from the shared pattern library (`diagonal-lines`, `polka-dots`, `crosshatch` …) for every series, drawn in its colour on a tint of it, for print and colour-blind reading. A list keeps its first entry; a mark under 20 px on its shorter side stays solid. |
| range | { lower: string; upper: string; label?: string } \| ChartRangeHighlight |  | `{ from, to, label? }`: a highlighted range of categories (grey stripes behind the marks), on every variant. `{ lower, upper }`: the min/max band of `range-area` (fields in each datum) drawn behind the line. |
| rangeBand | ChartRangeBand |  | A band around a series from two fields, faded at both ends with its outline; the tooltip shows "42k · 38k – 47k". |
| rangeSelectable | boolean |  | Allow selecting a range by dragging or Shift + arrow keys. On when `onSelectedRangeChange` is set. |
| 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. |
| 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-area`: the value the area is split at (default 0). |
| thresholdLabel | string |  |  |
| 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-area" \| "gradient-area" \| "gradient-reverse-area" \| "stroke-area" \| "dashed-area" \| "step-area" \| "smooth-area" \| "overlap-area" \| "positive-negative-area" \| "range-area" \| "horizon-graph" \| "area-with-target-line" \| "difference-area" \| "area-line-overlay" \| "glow-area" | "basic-area" | Figma variant. Default `basic-area`. |
| 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

### Patterns

### Background texture

### Ghost trail

### Table view

## In context

### Requests by Status

API gateway monitoring: requests by status class with KPI cards. Reload shows the loading state.

### Cumulative Issues

Project insights: created against completed issues, added up. The period switch draws the chart in again.

### MRR by Plan

Subscription analytics: MRR per plan with KPI cards.

## For AI agents

`get_component("area-chart")`

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