<!-- Protocore Design System — AreaChart -->
# AreaChart

- **Category:** Charts (`charts`)
- **Slug:** `charts/area-chart`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { AreaChart } from "@protocore/pds/charts";`
- **Docs:** https://pds.protocore.io/components/charts/area-chart

> A monochrome-plus-signal area chart with a soft 0.10→0 gradient fill, recharts-backed.

## Import path

`AreaChart` ships from the **`@protocore/pds/charts`** subpath so recharts stays out of the core bundle. `recharts` (>=3) is an **optional peer**; install it in apps that render charts.

```tsx
import { AreaChart } from "@protocore/pds/charts";
import { ChartContainer } from "@protocore/pds";
```

## When to use it

Use **AreaChart** when *volume or accumulation* under a trend is the point — throughput, settled value, depth over time — and the filled region reinforces magnitude. When only the line's slope matters, prefer [LineChart](/charts/line-chart) (less ink). For discrete categories use [BarChart](/charts/bar-chart); for a glanceable frameless trend, [Sparkline](/charts/sparkline).

The same monochrome-plus-signal doctrine applies (see [ChartContainer](/charts/chart-container)): overlapping fills muddy fast, so rank series, keep supporting ones grey, and reserve the signal hues.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `ReadonlyArray<Record<string, string \| number \| null \| undefined>>` | yes | — | Row-oriented data; each datum keyed by `xKey` and by every series `key`. |
| `series` | `ChartSeries[]` | yes | — | Series to plot, in draw + legend order. `ChartSeries` = `{ key: string; label?: string; color?: string }` — color defaults to `--pds-chart-N` by position. |
| `xKey` | `string` | yes | — | Datum key for the x-axis category. |
| `height` | `number` | no | `240` | Chart height in px. |
| `...rest` | `Omit<RechartsAreaChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>` | no | — | Remaining props spread onto the underlying recharts `<AreaChart>` (e.g. `margin`, `stackOffset`, `syncId`). |

## Examples

### Basics

Same shape as [LineChart](/charts/line-chart) — `data`, `xKey`, `series` — plus a vertical gradient fill that fades from 10% opacity at the stroke to 0 at the baseline. The soft fill emphasizes accumulated magnitude without drowning the line.

```tsx
import { ChartContainer } from "@protocore/pds";
import { AreaChart } from "@protocore/pds/charts";

const data = [
  { t: "W1", volume: 12.4 },
  { t: "W2", volume: 13.1 },
  { t: "W3", volume: 11.8 },
  { t: "W4", volume: 15.2 },
  { t: "W5", volume: 17.6 },
  { t: "W6", volume: 19.0 },
];

export default function Demo() {
  return (
    <ChartContainer label="Settled volume / M USDC" height={240}>
      <AreaChart data={data} xKey="t" series={[{ key: "volume", label: "Volume" }]} />
    </ChartContainer>
  );
}
```

### Multiple series

Each series gets its own gradient keyed off its ramp color. Areas overlap by default (they don't stack) — keep it to two or three series so the fills stay readable, and pass recharts stacking props via `...rest` if you need a true stack.

```tsx
import { ChartContainer } from "@protocore/pds";
import { AreaChart, ChartLegend } from "@protocore/pds/charts";

const data = [
  { day: "Mon", mempool: 820, confirmed: 760 },
  { day: "Tue", mempool: 910, confirmed: 880 },
  { day: "Wed", mempool: 740, confirmed: 720 },
  { day: "Thu", mempool: 1030, confirmed: 970 },
  { day: "Fri", mempool: 1180, confirmed: 1120 },
];

const series = [
  { key: "mempool", label: "Mempool depth" },
  { key: "confirmed", label: "Confirmed" },
];

export default function Demo() {
  return (
    <ChartContainer
      label="Mempool vs confirmed / txns"
      legend={<ChartLegend items={series.map((s) => ({ label: s.label }))} />}
      height={240}
    >
      <AreaChart data={data} xKey="day" series={series} />
    </ChartContainer>
  );
}
```

## Do & don't

**Do**

- Reserve area fills for metrics where accumulated magnitude matters.
- Keep it to two or three series so overlapping fills stay legible.
- Wrap it in a ChartContainer so it inherits the `--pds-chart-*` ramp.
- Give each series a human `label` for the legend and tooltip.

**Don't**

- Don't stack many opaque areas — the gradient is faint but overlaps still muddy.
- Don't use it when only the slope matters — a LineChart carries less ink.
- Don't import it from `@protocore/pds`; it lives on the `/charts` subpath.
- Don't rely on fill hue alone to separate series — pair with a legend.

## Accessibility

**Notes**

- recharts renders the plot as SVG; provide surrounding context (a ChartContainer `label`, caption, or data table) since the marks are not individually labelled.
- The gradient fill is decorative — series identity rests on the stroke color and the legend, and the ramp keeps a luminance spread for grayscale/CVD readers.
- The default tooltip surfaces per-series values on hover and keyboard focus via recharts.

## Related

`line-chart`, `bar-chart`, `chart-container`, `sparkline`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/