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

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

> A monochrome-plus-signal funnel chart with sharp trapezoids and inline mono stage labels, recharts-backed.

## Import path

`FunnelChart` ships from the **`@protocore/pds/charts`** subpath. `recharts` (>=3) is an **optional peer**.

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

## When to use it

Use **FunnelChart** for a *monotonically narrowing* progression through ordered stages — visited → signed up → activated → paid. If the parts don't nest (a plain part-to-whole split), use a [PercentageBarChart](/charts/percentage-bar-chart); for unordered category comparison use a [BarChart](/charts/bar-chart).

Order stages widest → narrowest and reserve a signal hue for the stage whose drop-off matters.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `ReadonlyArray<Record<string, string \| number \| null \| undefined>>` | yes | — | One datum per stage; each keyed by `nameKey` (label) and `dataKey` (value). |
| `dataKey` | `string` | no | `"value"` | Datum key for each stage's numeric value. |
| `nameKey` | `string` | no | `"name"` | Datum key for each stage's label. |
| `colors` | `string[]` | no | `--pds-chart-N ramp` | Per-stage colour overrides, in data order. |
| `height` | `number` | no | `240` | Chart height in px. |
| `...rest` | `Omit<RechartsFunnelChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>` | no | — | Remaining props spread onto the underlying recharts `<FunnelChart>`. |

## Examples

### Basics

Pass `data` as ordered stages of `{ name, value }`, widest first. Each trapezoid is sharp (no rounding), coloured from the ramp with a hairline surface-coloured separator, and labelled inline in mono.

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

const data = [
  { name: "Visited", value: 1000 },
  { name: "Signed up", value: 620 },
  { name: "Activated", value: 310 },
  { name: "Paid", value: 90 },
];

export default function Demo() {
  return (
    <ChartContainer label="Activation funnel" height={260}>
      <FunnelChart data={data} />
    </ChartContainer>
  );
}
```

## Do & don't

**Do**

- Order stages widest to narrowest — the funnel implies a monotonic drop.
- Keep stage labels short so the inline labels stay legible.
- Wrap it in a ChartContainer so it inherits the `--pds-chart-*` ramp.
- Spend a signal hue on the stage with the critical conversion.

**Don't**

- Don't use it for non-nesting parts — that's a PercentageBarChart.
- Don't round the trapezoids or add shadows; keep the geometry sharp.
- Don't import it from `@protocore/pds`; it lives on the `/charts` subpath.
- Don't reorder stages out of their real sequence.

## Accessibility

**Notes**

- recharts renders the plot as SVG; provide surrounding context (a ChartContainer `label` or a data table) for assistive tech.
- Stages are labelled inline, so identity does not rely on colour alone.

## Related

`percentage-bar-chart`, `bar-chart`, `chart-container`

---

© 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/