# AreaChart

Filled areas, stacked or expanded, solid or gradient, with a crosshair tooltip.

```ehtml Example
import { AreaChart } from "@elements/ui/chart-area";
import type { ChartConfig } from "@elements/ui/chart";

<AreaChart data={rows} {config} x="month" curve="natural" />
<AreaChart data={rows} {config} x="month" series={["mobile", "desktop"]}
           stack="normal" fill="gradient" legend />
```

## Parts

| Part | What it is |
|---|---|
| `AreaChart` | The template. One filled area per series. |
| `.chart-area-mark` | One area (an SVG path); .is-gradient with fill=gradient. |
| `.chart-line-mark` | The area's top edge, unless stroke is false. |
| `.chart-dot` | Point markers, as LineChart. |
| `.chart` | The figure. Declares `--color-<key>` for each config entry; keeps a 16:9 box unless sized by class. |
| `.chart-plot` | The focusable plot area holding the SVG; one tab stop. |
| `.chart-tooltip` | The tooltip: heading, one row per item with swatch, name and value, optional footer. |
| `.chart-legend` | The legend row; .chart-legend-item per series, a button with legend toggle. |
| `.chart-table` | The data as a table, visually hidden unless showTable. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `data` | `Row[]` | (required) | The rows: one per category. |
| `config` | `ChartConfig` | (required) | The chart config: per data key a label, a color (any CSS color, usually var(--chart-N)) or a theme { light, dark }, and an optional icon; legendType and tooltipType; strokeDasharray and strokeOpacity dash and fade a line or an area's edge. Each key becomes `--color-<key>` on the chart. |
| `x` | `string` | (required) | The category field. |
| `series` | `string[]` | `[]` | The value fields, first at the bottom of a stack. Empty draws every numeric config key. |
| `curve` | `"linear" \| "monotone" \| "natural" \| "step" \| "stepBefore" \| "stepAfter" \| "basis" \| "bump"` | `"linear"` | How the edges join their points. |
| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | vertical runs the categories down the chart and the values across it. |
| `stack` | `"none" \| "normal" \| "expand" \| "silhouette" \| "wiggle"` | `"none"` | Stack the areas; expand fills the plot so each area is its share; silhouette and wiggle center the layers as a streamgraph. |
| `reverseStackOrder` | `boolean` | `false` | Stack the last series first, so the first sits on top; the legend and tooltip keep series order. |
| `baseValue` | `number \| "dataMin" \| "dataMax" \| null` | `null` | Where an unstacked area fills to: a value, or the bottom or top of the axis. null fills to zero. |
| `fill` | `"solid" \| "gradient"` | `"solid"` | A flat wash, or a gradient that fades from the line down. |
| `fillOpacity` | `number` | `-1` | 0 to 1. -1 follows the theme. |
| `stroke` | `boolean` | `true` | Draw each area's top edge. |
| `strokeWidth` | `number` | `0` | Edge width in px. 0 follows the theme. |
| `dots` | `boolean \| { r?: number; shape?: "circle" \| "square" \| "diamond" \| "commit"; colorByRow?: boolean; nameKey?: string; hollow?: boolean }` | `false` | A marker on every point. |
| `activeDot` | `boolean \| { r?: number; shape?: "circle" \| "square" \| "diamond" \| "commit"; colorByRow?: boolean; nameKey?: string; hollow?: boolean }` | `true` | The markers at the active point. |
| `connectNulls` | `boolean` | `false` | Fill across missing values. |
| `categoryAxis` | `boolean \| { tickFormatter?: (value, index) => string; tickLine?: boolean; axisLine?: boolean; tickMargin?: number; tickCount?: number; domain?: [number \| "auto" \| "dataMin" \| "dataMax", ...]; size?: number; showAll?: boolean; minTickGap?: number; orientation?: "left" \| "right" \| "top" \| "bottom"; series?: string[]; key?: string; hide?: boolean; reversed?: boolean; angle?: number; label?: string \| { value, offset? }; unit?: string; ticks?: (number \| string)[]; allowDecimals?: boolean; allowDataOverflow?: boolean; niceTicks?: "auto" \| "none"; interval?: number \| "preserveEnd" \| "preserveStart" \| "preserveStartEnd" \| "equidistantPreserveStart"; padding?: { left?, right?, top?, bottom? }; scale?: "linear" \| "log" \| "sqrt"; type?: "category" \| "number"; mirror?: boolean; tickSize?: number; tick?: boolean; includeHidden?: boolean; allowDuplicatedCategory?: boolean } \| AxisOptions[]` | `true` | The category axis. A list draws several, such as a second on the other side showing another field (key, orientation). Options: reversed, angle, label, interval, padding, type number, tickSize, tick, allowDuplicatedCategory. |
| `valueAxis` | `boolean \| { tickFormatter?: (value, index) => string; tickLine?: boolean; axisLine?: boolean; tickMargin?: number; tickCount?: number; domain?: [number \| "auto" \| "dataMin" \| "dataMax", ...]; size?: number; showAll?: boolean; minTickGap?: number; orientation?: "left" \| "right" \| "top" \| "bottom"; series?: string[]; key?: string; hide?: boolean; reversed?: boolean; angle?: number; label?: string \| { value, offset? }; unit?: string; ticks?: (number \| string)[]; allowDecimals?: boolean; allowDataOverflow?: boolean; niceTicks?: "auto" \| "none"; interval?: number \| "preserveEnd" \| "preserveStart" \| "preserveStartEnd" \| "equidistantPreserveStart"; padding?: { left?, right?, top?, bottom? }; scale?: "linear" \| "log" \| "sqrt"; type?: "category" \| "number"; mirror?: boolean; tickSize?: number; tick?: boolean; includeHidden?: boolean; allowDuplicatedCategory?: boolean } \| AxisOptions[]` | `false` | The value axis. A list adds axes, each scaling the series it names, on the other side with orientation. Options: reversed, unit, ticks, allowDecimals, allowDataOverflow, niceTicks, scale (linear, log, sqrt), mirror, label, includeHidden. |
| `grid` | `boolean \| { horizontal?: boolean; vertical?: boolean; strokeDasharray?: string; fill?: string; fillOpacity?: number; horizontalFill?: string[]; verticalFill?: string[]; horizontalValues?: (number \| string)[]; verticalValues?: (number \| string)[]; horizontalPoints?: number[]; verticalPoints?: number[]; horizontalCoordinatesGenerator?: (plot) => number[]; verticalCoordinatesGenerator?: (plot) => number[]; syncWithTicks?: boolean }` | `true` | The grid: horizontal lines at the value ticks by default, vertical on request; dashed lines, a background fill and stripes between the lines; lines at given values or pixels; syncWithTicks keeps the category lines to the ticks that show. |
| `labels` | `boolean \| LabelOptions \| LabelOptions[]  (LabelOptions: { position?, key?, series?, formatter?: (value, row) => string, offset?, color?, class? })` | `false` | Values above each point. |
| `tooltip` | `boolean \| { indicator?: "dot" \| "line" \| "dashed"; hideLabel?: boolean; hideIndicator?: boolean; color?: string; labelKey?: string; nameKey?: string; labelFormatter?: (label, row) => string; formatter?: (value, key, row) => string; footer?: (row) => string; footerLabel?: string; unit?: string; defaultIndex?: number; cursor?: boolean; filterNull?: boolean; trigger?: "hover" \| "click"; active?: boolean; position?: { x?, y? }; reverseDirection?: { x?, y? }; itemSorter?: "name" \| "value" \| "key" \| (item) => number \| string; includeHidden?: boolean; animationDuration?: number; animationEasing?: string \| (t) => number; isAnimationActive?: boolean }` | `true` | The tooltip: false turns it off; an object sets the indicator, hides the heading or swatches, takes names and headings from other keys, formats them, adds a footer line, or turns off the hover cursor. More options: trigger click (a click shows it and it stays), active (always or never shown), position (a fixed spot), reverseDirection, itemSorter and includeHidden. |
| `legend` | `boolean \| { position?: "top" \| "bottom" \| "left" \| "right" \| "center" \| "insideTop" \| "insideBottom" \| "insideLeft" \| "insideRight" \| "insideTopLeft" \| "insideTopRight" \| "insideBottomLeft" \| "insideBottomRight" \| { x, y }; offset?: number; iconSize?: number; verticalAlign?: "top" \| "middle" \| "bottom"; align?: "left" \| "center" \| "right"; layout?: "horizontal" \| "vertical"; iconType?: "square" \| "rect" \| "circle" \| "line" \| "plainline" \| "diamond" \| "triangle" \| "cross" \| "star" \| "wye" \| "none"; formatter?: (name, key) => string; itemSorter?: "name" \| "key" \| (item) => number \| string; hideIcon?: boolean; nameKey?: string; toggle?: boolean }` | `false` | The legend: above or below the plot, or beside it with verticalAlign middle; position puts it beside the plot, over it at an inside spot or the center, or at a point, offset moves it, iconSize sizes the swatch; align, a vertical layout, the swatch shape (iconType), a name formatter and an itemSorter; names from another key; toggle makes each item a button that hides its series. |
| `margin` | `{ top?, right?, bottom?, left? }` | `{}` | Space around the plot in px; each side defaults to 5. |
| `active` | `number` (two-way) | `-1` | The active item index. Hover and the arrow keys move it; when the pointer leaves it returns to the value it had. |
| `hidden` | `string[]` (two-way) | `[]` | Series keys not drawn. They stay in the legend, where a toggle legend shows them again. |
| `label` | `string` | `"Area chart"` | The chart's accessible name and its table's caption. |
| `animate` | `boolean` | `true` | Marks enter with motion and move to new values. Off under prefers-reduced-motion. |
| `animation` | `{ begin?: number; duration?: number; easing?: string \| (t) => number; matchBy?: "index" \| "append" \| (item, index) => key; interpolate?: (items, t) => items; newValues?: boolean }` | `{}` | Times the entry and the move to new data. matchBy pairs old and new items by position or by a key, matchByDataKey(field) from the chart package; interpolate draws every frame of a change from the paired items and the eased time; newValues false shows an unpaired new point at once. |
| `showTable` | `boolean` | `false` | Show the chart's data table under the plot. The table is always in the accessibility tree. |
| `class` | `string` | `""` | Classes on the figure. Size the chart here: it keeps a 16:9 box unless given a height or aspect-ratio. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Any other attributes for the figure: id, data-testid, aria-\*. |
| `syncId` | `string` | `""` | Charts with the same syncId share the active item and its tooltip. |
| `syncMethod` | `"index" \| "value"` | `"index"` | Match the shared item by position, or by its category or name. |
| `onActiveChange` | `(index: number) => void` | `() => {}` | The user moved the active item (hover, leave or keys). |
| `onItemClick` | `(index: number) => void` | `() => {}` | A click or tap on an item, with its index. |
| `onHiddenChange` | `(hidden: string[]) => void` | `() => {}` | A legend toggle changed hidden. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Focuses the chart (one tab stop) and shows the tooltip for the item the keys last reached, else the active item, else the first. |
| `ArrowRight / ArrowDown` | Next item. The same under dir=rtl: the plot is not mirrored, so keys follow the screen. |
| `ArrowLeft / ArrowUp` | Previous item. |
| `Home / End` | First and last item. |
| `Escape` | Hides the tooltip. In a dialog, the dialog stays open until the next Escape. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-chart` | `"bar" \| "line" \| "area" \| "pie" \| "radar" \| "radial"` | figure |
| `data-state` | `"open" \| "closed"` | .chart-tooltip |
| `data-index` | the item index | .chart-hit and pie, radial marks |
| `data-series` | the series key | marks |
| `data-resizing` | present while the chart redraws for a new size | figure |
| `data-entered` | present once the entry motion is over | figure |
| `aria-pressed` | true \| false | .chart-legend-item (toggle) |

## Accessibility

- The plot is one tab stop: role=group, aria-roledescription=chart, named by label, described by the data table.
- The SVG is aria-hidden; a screen reader gets the data from the table, which every chart renders.
- Arrow keys move through the items and each move is announced in a polite live region, for example "February: Desktop 305, Mobile 200".
- Identity is never color alone: a legend for two or more series and labels on the tooltip rows.
- Legend toggles are buttons with aria-pressed.

## See also

- [Chart](chart): What every chart shares: the config and its colors, the tooltip, the legend, the palette and the data table.
- [BarChart](chart-bar): Vertical, horizontal, stacked and grouped bars with tooltip, legend and labels.
- [LineChart](chart-line): Lines over categories with dots, curves, labels and a crosshair tooltip.
- [PieChart](chart-pie): Pie and donut charts with labels, a center value, an active slice and stacked rings.
- [RadarChart](chart-radar): Values on radial axes, one polygon per series, over a polygon or circle grid.
- [RadialChart](chart-radial): Radial bars and gauges, with tracks, labels along the arc and a center value.