# Area Chart (/docs/charts/components/area)

Use an area chart to show how a measure changes across ordered categories, like months, when its size matters as much as its trend. Stack areas to show how parts add up to a total.

<Example caption="Hover the area, or focus the chart and press the arrow keys, to see each month's value.">
<Basic />

```tsx
"use client";

import { AreaChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { month: "Jan", visitors: 420 },
  { month: "Feb", visitors: 580 },
  { month: "Mar", visitors: 510 },
  { month: "Apr", visitors: 760 },
  { month: "May", visitors: 680 },
  { month: "Jun", visitors: 910 },
  { month: "Jul", visitors: 840 },
  { month: "Aug", visitors: 1070 },
  { month: "Sep", visitors: 960 },
  { month: "Oct", visitors: 1180 },
  { month: "Nov", visitors: 1110 },
  { month: "Dec", visitors: 1360 },
];

const config = {
  visitors: { label: "Visitors", color: "#733bff" },
} satisfies SeriesConfig;

export default function VisitorsChart() {
  return (
    <AreaChart
      data={data}
      config={config}
      animate
      margin={{ right: 16 }}
      aria-label="Monthly visitors"
    >
      <AreaChart.Grid />
      <AreaChart.XAxis dataKey="month" />
      <AreaChart.YAxis width={40} />
      <AreaChart.Series dataKey="visitors" type="monotone" strokeWidth={2} fillOpacity={0.25} />
      <AreaChart.Tooltip />
      <AreaChart.Legend />
    </AreaChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/area-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
AreaChart
├── AreaChart.Background
├── AreaChart.Grid
├── AreaChart.XAxis
├── AreaChart.YAxis
├── AreaChart.Series
├── AreaChart.Tooltip
├── AreaChart.Legend
└── AreaChart.Content
```

`AreaChart` holds the data, the series config and the accessible name, and draws only the parts you add. Add one `AreaChart.Series` per area. The tooltip and legend read their labels and colors from `config`. `AreaChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Series [#series]

Each `AreaChart.Series` fills the `dataKey` it names, and takes its label and color from the matching `config` entry. Set `type` for the curve (`linear` by default, `monotone` for a smooth edge, `stepAfter` for steps) and `fillOpacity` to keep the grid visible through the fill.

A `null` value leaves a gap in the area. Pass `connectNulls` to the series to fill across it instead.

### Stacking [#stacking]

Give series the same `stackId` to stack them, so the top edge shows the total:

<Example caption="Press Desktop or Mobile in the legend to highlight that area.">
<Stacked />

```tsx
"use client";

import { AreaChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { month: "Jan", desktop: 310, mobile: 110 },
  { month: "Feb", desktop: 380, mobile: 200 },
  { month: "Mar", desktop: 340, mobile: 170 },
  { month: "Apr", desktop: 460, mobile: 300 },
  { month: "May", desktop: 390, mobile: 290 },
  { month: "Jun", desktop: 520, mobile: 390 },
  { month: "Jul", desktop: 450, mobile: 390 },
  { month: "Aug", desktop: 580, mobile: 490 },
  { month: "Sep", desktop: 500, mobile: 460 },
  { month: "Oct", desktop: 610, mobile: 570 },
  { month: "Nov", desktop: 540, mobile: 570 },
  { month: "Dec", desktop: 650, mobile: 710 },
];

const config = {
  desktop: { label: "Desktop", color: "#733bff" },
  mobile: { label: "Mobile", color: "#14a39a" },
} satisfies SeriesConfig;

export default function DeviceChart() {
  return (
    <AreaChart
      data={data}
      config={config}
      animate
      margin={{ right: 16 }}
      aria-label="Monthly visitors by device"
    >
      <AreaChart.Grid />
      <AreaChart.XAxis dataKey="month" />
      <AreaChart.YAxis width={40} />
      <AreaChart.Series dataKey="desktop" stackId="visitors" type="monotone" fillOpacity={0.35} />
      <AreaChart.Series dataKey="mobile" stackId="visitors" type="monotone" fillOpacity={0.35} />
      <AreaChart.Tooltip />
      <AreaChart.Legend />
    </AreaChart>
  );
}
```
</Example>

Stacks keep their layout when a series is hidden, so the other areas don't jump. To show each part as a share of the total, set `stackOffset="expand"` on the chart and format the axis and tooltip with `createPercentStack`; see [Combo Chart](./combo.mdx#percentage-stacks).

### Legend and Keyboard [#legend-and-keyboard]

Pressing a legend item highlights its area and dims the others, and screen readers hear "Highlighted Desktop." Press it again, or press Escape, to clear it. To hide and show areas from the legend instead, see [Legend](../building-blocks/legend.mdx).

Focus the chart and press the arrow keys to move between months, which shows the tooltip, and Escape to dismiss it.

### Points, Patterns and Materials [#points-patterns-and-materials]

Areas have no points by default. Pass `dot` to show them, and `pointStyle="border"` or `"colored-border"` for outlined points; `activePointStyle` paints the point under the cursor. Set `pattern` to fill an area with hatching or dots instead of a flat color, which helps when colors alone are hard to tell apart:

```tsx
<AreaChart.Series dataKey="mobile" stackId="visitors" pattern={{ kind: "hatch" }} />
```

Set `material="clay"` or `"glow"` on a series for a finish; see [Materials](../guides/materials.mdx).

### Motion [#motion]

Areas appear at once unless you set `animate`. Pass `true` to draw them in from left to right, or options to change the direction or the duration:

```tsx
<AreaChart animate={{ revealDirection: "center-out", revealDurationMs: 800 }} {...props}>
```

`revealDirection` is `left-to-right`, `right-to-left`, `center-out` or `edges-in`. When the reader prefers reduced motion, areas appear without drawing in. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder area that sweeps across the plot, or holds still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default). The legend and tooltip come back when `loading` turns off:

```tsx
<AreaChart loading={isPending} loadingLabel="Loading visitors" {...props}>
```

### Background [#background]

Add `AreaChart.Background` for a decorative pattern behind the plot: `pinpoints`, `crossings` or `waves`. It adds nothing to the tooltip, legend or accessible name.

```tsx
<AreaChart.Background pattern="waves" opacity={0.15} />
```

## API Reference [#api-reference]

### AreaChart [#areachart]

### AreaChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                              |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                                 |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                                       |
| `animate?`               | `boolean \| LineAnimation \| undefined`                                                                                                                                                                                                              | Draws the areas in on mount. Pass `true` or options to change the direction or duration. Reduced motion skips it. Default: `false` |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                            |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                         |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                           |
| `emphasis?`              | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                                    |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                            |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                       |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                              |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                             |
| `data?`                  | `ChartData<unknown> \| undefined`                                                                                                                                                                                                                    | The rows to plot. Each series reads its `dataKey` from every row.                                                                  |

### AreaChart.Series [#areachartseries]

### AreaSeriesOptions

| Prop                | Type                                        | Description                                                                                                                                                   |
| ------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seriesKey?`        | `string \| undefined`                       | The `config` key for this series. Required when `dataKey` is a function or a number.                                                                          |
| `pointStyle?`       | `"border" \| "colored-border" \| "default"` | How each point is painted, when you show points. A `dot` you pass replaces it. Default: `"default"`                                                           |
| `activePointStyle?` | `"border" \| "colored-border" \| "default"` | How the inspected point is painted. An `activeDot` you pass replaces it. Default: `"default"`                                                                 |
| `material?`         | `"clay" \| "glow" \| "plain"`               | A finish for the area. A custom `shape` or `filter` replaces it. Default: `"plain"`                                                                           |
| `pattern?`          | `false \| FillPattern \| undefined`         | Fills the area with a pattern instead of a flat color. Defaults to the `pattern` in `config`; `false` turns it off. A `fill` or `shape` you pass replaces it. |

<Caption>
`AreaChart` and `AreaChart.Series` also take every prop of Recharts' [AreaChart](https://recharts.github.io/en-US/api/AreaChart/) and [Area](https://recharts.github.io/en-US/api/Area/), like `margin`, `stackOffset`, `type`, `stackId` and `connectNulls`.
</Caption>