# Funnel Chart

Funnel chart for conversion between steps: trapezoid funnel and pyramid, bar funnels and KPI-column funnel areas, with the step conversion in the tooltip.

- Category: Charts
- Page: https://wunderui.com/components/funnel-chart
- Tier: Core and Pro

## Install

Funnel Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { FunnelChart, FunnelChartLook, FunnelChartProps, FunnelChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { FunnelChart } from "@wunderui/react/charts"

const data = [
  { name: "Visitors", value: 48200 },
  { name: "Sign-ups", value: 12900 },
  { name: "Activated", value: 7400 },
  { name: "Paid", value: 1500 },
]

export function ConversionFunnel() {
  return <FunnelChart data={data} index="name" label="Conversion funnel" />
}
```

Expected result: You see four stages narrowing from Visitors to Paid. Hovering a stage shows its value and the conversion from the previous one.

## When to use

### Use Funnel Chart for

- How a count drops through ordered stages: visitors to paid accounts
- A checkout or an onboarding with the drop-off from each stage
- A pyramid for a layered model
- Two sides compared (mirrored funnel), or this period against the last

### Use something else

- [Waterfall Chart](https://wunderui.com/components/waterfall-chart) for changes that add up and subtract
- [Sankey Chart](https://wunderui.com/components/sankey-chart) for flows that split between stages
- [Bar Chart](https://wunderui.com/components/bar-chart) for stages that are not ordered
- [Progress Chart](https://wunderui.com/components/progress-chart) for completion against a target

## Keyboard

The plot is focusable: arrow keys step through the stages, and the live region reads each with its value and its conversion from the first and previous stage.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous stage. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last stage. |
| `Escape` | Clears the active point. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

What the chart does on its own and what the page decides.

- **Stages:** Each row of the data is a stage, widest first. You say which field holds the stage name and which holds the count.
- **Options by variant:** Mirror adds a second side (indigo against pink) and side labels name the two. Previous draws a pale band of the earlier period behind the area funnels, color sets the area colour, palette="series" swaps the indigo tones for the palette order and colors sets one colour per stage. Twelve looks: the other Figma names (funnel-area-with-plateau, funnel-area-7-steps, funnel-area-6-steps, compact-funnel-area, rising-funnel-area, compact-flared-funnel-area, compact-rounded-step-funnel-area, rising-step-funnel-area) are aliases that draw one of them (FUNNEL_VARIANT_ALIASES).
- **Conversion:** The stepped variants show the share carried over from the stage before as a badge. The tooltip gives From previous and From first percentages for every stage after the first.
- **Hover:** The stage under the pointer or focus turns two steps lighter in its own colour scale, with a near-black label that stays readable in light and dark.
- **Loading, empty and error:** The chart keeps its size while loading, empty or failed, so the card never changes height. Add a retry handler to show a Try again button on error.
- **Legend:** A ChartCard shows series as badges. With two or more series each badge toggles its series, the last visible one stays on, and a legend of roles can be made static.
- **Data table:** The chart also renders its data as a table for screen readers, in plot order.
- **Size:** The chart fills the width of its container, and you set the plot height. Text never scales: labels keep their size at every width.

## Motion

The enter sequence and hover follow the library's motion tokens.

- **Enter:** Marks play an enter sequence the first time the chart is in view, and again after loading or when new data arrives. You can turn it off.
- **Reduced motion:** With reduced motion the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

## Anatomy

- `FunnelChart`: Takes one row per stage, with the stage name and its value. Options add a mirrored second side, a pale band for the previous period, an area colour and side labels.
- `Plot`: The focusable region. Arrow keys walk the marks and the live region reads each one as the tooltip shows it.
- `Marks`: The stage shapes, drawn from the widest in the indigo tones (600 for the first stage down to 200). Trapezoids open from the funnel's axis, top to bottom; the area looks draw a smooth, curved, stepped or flared surface across the KPI columns, strongest at its value edge.
- `Hover`: The stage under the pointer or focus keeps its strength and every other stage dims to --chart-dim, the hover of every chart. On the area looks the area dims (--chart-dim-area) and the hovered stage's part of the same area stays, cut at the column edges.
- `Conversion badges`: On the stepped variants, the share carried over from the stage before, so the drop is stated and not left to the eye.
- `Tooltip`: The stage value (and the second side on the mirrored funnel), then From previous and From first percentages for every stage after the first.
- `Loading, empty and error`: Five muted bars of falling width stand in for the stages while loading. A retry handler adds a Try again button to the error message.
- `Data table and live region`: A table of the stages and values for screen readers.
- `Funnel Area`
- `Funnel Previous`
- `Chart Hover Stage`

## Best practices

### When to use

- Use FunnelChart for a sequence where each stage is a subset of the one before, such as visits, sign-ups, trials and paid. Use PieChart for parts of a whole and SankeyChart for flow between stages.

### Do

- Order the data from first stage to last and keep it to four to seven stages. If a stage can grow above the previous one, a funnel is the wrong model.
- Print the numbers. Trapezoid width is easy to misjudge, so show the count and the conversion in the label or badge.
- Use the mirrored funnel only for two groups with the same stages, such as two plans, and name them with side labels.

### Don't

- Don't use the area variants without KPI numbers beside them. They are a backdrop for a metric row, not a chart to read alone.
- Don't mix absolute counts and percentages across stages. Every stage uses the same unit.

## API reference

### FunnelChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per slice / ring / axis. |
| index* | string |  | Field holding the label. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| className | string |  | Extra classes for the root element of the chart. |
| color | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" | "indigo" | Area variants and the stepped funnel: colour of the area / the bars (default indigo). |
| colors | readonly ChartColor[] |  | Colours per row, in order (palette names or token expressions). |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| height | number |  | Height of the plot frame in px. Default 280 (Figma small card plot). |
| hiddenSeries | readonly string[] |  | Labels of rows switched off in the legend: drawn faded. |
| label | string |  | Accessible name, e.g. the card title. |
| mirror | string |  | `mirrored-funnel`: field of the second side (the first is `value`). |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| palette | "indigo" \| "series" | "indigo" | Stage colours when `colors` is not set: `indigo` (default) gives the stages the indigo tonal scale, 600 for the first stage down to 200 — one hue, because the stages are parts of one flow; `series` takes the palette order. |
| pattern | ChartPattern \| ChartPattern[] |  | One pattern form from the shared pattern library (`diagonal-lines`, `polka-dots`, `crosshatch` …) for every stage (or the funnel area), drawn in its colour on a tint of it, for print and colour-blind reading. A list keeps its first entry; a mark under 20 px on its shorter side stays solid. |
| previous | string |  | Area variants: field of the previous period, drawn as a pale band behind. |
| sideLabels | readonly [string, string] | ["A", "B"] | Labels of the two sides of the mirrored funnel. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| tooltip | boolean |  |  |
| value | string |  | Field holding the value. Default "value". |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "vertical-funnel" \| "horizontal-funnel" \| "pyramid" \| "mirrored-funnel" \| "stepped-funnel" \| "funnel-area" \| "funnel-area-7-steps" \| "funnel-area-6-steps" \| "flared-funnel-area" \| "rounded-step-funnel-area" \| "step-funnel-area" \| "funnel-area-edge-fade" \| "flared-step-funnel-area" \| "compact-funnel-area" \| "funnel-area-with-plateau" \| "rising-funnel-area" \| "compact-flared-funnel-area" \| "compact-rounded-step-funnel-area" \| "rising-step-funnel-area" \| "curved-funnel-area" | "vertical-funnel" | Variant (a look or one of its aliases). Default `vertical-funnel`. |
| width | number |  |  |

## Examples

### States

### Stage colours

### Variant names

### Patterns

## In context

### Signup to Purchase Funnel

Stepped funnel with conversion badges and KPIs.

### Sales Pipeline Stages

Deals by stage next to the stuck deals.

### Checkout Drop-off

KPI-column funnel area against last month, with drop-off reasons.

## For AI agents

`get_component("funnel-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
