# FunnelChart

Stages that only ever narrow.

- Group: Charts
- Import: `import { FunnelChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/funnel-chart/
- Related: sankey-chart, bar-chart

## When to reach for it

A signup flow, a hiring pipeline, a checkout. When the flow can SPLIT rather than only shrink, it is a SankeyChart — a funnel has one path through it by construction.

## Accessibility

- title is required; the stages are also rendered as a visually hidden table.
- The taper encodes a ratio between neighbouring stages and the eye reads the enclosed area, so a funnel exaggerates a shallow drop. Compose a Label to print the numbers — that is the relief.
- The default variant holds one fill for every stage and lets the shape carry the drop. A ramp that also darkens each stage encodes the same fact twice.

## FunnelChart

Stages that only ever narrow — a signup flow, a hiring pipeline, a checkout. The caveat is the same one every funnel has: the taper encodes a RATIO between neighbouring stages, and the eye reads the enclosed area, so a funnel exaggerates a shallow drop and flattens a steep one. Where the exact fall-off is the point, put the percentages on the stages — `<Funnel.Label>` does — or use a `<BarChart>`, which encodes each stage on one honest scale. Reach for `<SankeyChart>` instead when the flow can SPLIT rather than only shrink: a funnel has one path through it by construction.

### Props

- `config` (required) — `ChartConfig`. Stage names → their label and paint. Keys must match the `nameKey` values.
- `data` (required) — `TData[]`. The stages, widest first. Order is the funnel; it is not sorted for you.
- `dataKey` (required) — `keyof TData & string`. The row field holding each stage's number.
- `nameKey` (required) — `keyof TData & string`. The row field naming each stage.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — `<Funnel>`, `<Tooltip>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsFunnelChart>`. Escape hatch onto the raw Recharts chart element.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.

## Example — default

```tsx
import { FunnelChart, type ChartConfig } from '@misoto22/design/charts'

<FunnelChart
  title="Signup funnel"
  config={config}
  data={stages}
  dataKey="people"
  nameKey="stage"
>
  <FunnelChart.Funnel>
    <FunnelChart.Label />
  </FunnelChart.Funnel>
  <FunnelChart.Tooltip />
</FunnelChart>
```

## Example — variant

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { FunnelChart, type ChartConfig, type FunnelVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as FunnelVariant)}
    aria-label="Stage fill"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <FunnelChart
    title={`Signup funnel — ${variant}`}
    config={config}
    data={stages}
    dataKey="people"
    nameKey="stage"
  >
    <FunnelChart.Funnel variant={variant} gap={3}>
      <FunnelChart.Label dataKey="people" position="center" />
    </FunnelChart.Funnel>
    <FunnelChart.Tooltip />
  </FunnelChart>
</div>
```