# Funnel chart

How much of a total survives each step of a process, in order.

- Component: `<FunnelChart />`, imported from `em-kit`
- Required props: `sectionDimension`, `countMeasure` and `results`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/funnel-chart
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/funnel-chart/playground

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A chart fills its parent, so the parent needs a height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## Usage

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <FunnelChart
        title="Deals by stage"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

- Steps sort largest first. When a later step can outgrow an earlier one, pass the optional `orderDimension`: a field holding each step’s position.

## States

The chart draws its own states from `results`: a skeleton while `isLoading` is true and it has no rows, a spinner in the header while it reloads rows it already has, an empty state when `data` is `[]`, and the message when `error` is set. Pass your query’s state straight through.

## Examples

### Step names on the funnel

Each step named on the funnel beside its value, with no legend: for a wide card. `showSectionLabels` writes “Step: value” on each step, so a legend would repeat the names.

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <FunnelChart
        title="Deals by stage"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
        showLegend={false}
        showSectionLabels
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

### Share of all steps

Each step as a share of all steps added together, not a conversion rate. `displayPercentages` divides by the total of every step.

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <FunnelChart
        title="Deals by stage, as a share of all steps"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
        displayPercentages
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

### Proportional bars

No taper: plain bars whose widths are exactly proportional, at the cost of the funnel look. `shrinkAnchor="none"` turns the taper off.

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <FunnelChart
        title="Deals by stage"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
        shrinkAnchor="none"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

### Custom colour ramp

A ramp between two colours of your choice, from the first step to the last. Set `startColor` and `endColor`; with one of them, the other is generated.

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <FunnelChart
        title="Deals by stage"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
        startColor="#0ea5e9"
        endColor="#1e3a8a"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

### In a small card

A card 320px wide, with the steps in the legend and the counts in the tooltips. `showValueLabels={false}` keeps the narrow last steps clean.

```tsx
import {
  ChartsProvider,
  FunnelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const dealStage = dimension({ name: 'deal_stage', title: 'Stage' });
const deals = measure({ name: 'deals', title: 'Deals' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ width: 320, height: 360 }}>
      <FunnelChart
        title="Deals by stage"
        sectionDimension={dealStage}
        countMeasure={deals}
        results={results(rows)}
        showValueLabels={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { deal_stage: 'Lead', deals: 4820 },
  { deal_stage: 'Qualified', deals: 2796 },
  { deal_stage: 'Proposal', deals: 1901 },
  { deal_stage: 'Negotiation', deals: 1369 },
  { deal_stage: 'Won', deals: 903 },
];
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `sectionDimension` | `Dimension` | yes |  | The dimension whose values are the funnel’s steps. Rows with the same step are added up. |
| `countMeasure` | `Measure` | yes |  | The measure that sizes each step. |
| `results` | `DataResponse` | yes |  | Your query’s state: `{ isLoading, data, error }`, where `data` is your rows. `results(rows)` builds it from an array. |
| `orderDimension` | `Dimension` | no |  | A numeric field giving each step’s position, lowest first. Without it, steps run largest to smallest. |
| `startColor` | `string` | no |  | Colour of the first step. The steps between blend towards `endColor`. |
| `endColor` | `string` | no |  | Colour of the last step. With only one of the two set, the other is generated. |
| `showLegend` | `boolean` | no | `true` | Show the legend. Entries wrap onto more lines when they do not fit. |
| `showTooltips` | `boolean` | no | `true` | Show a formatted tooltip on hover. |
| `showValueLabels` | `boolean` | no | `true` | Print each value on the chart. |
| `showSectionLabels` | `boolean` | no | `false` | Print each step’s name on its bar. With `showValueLabels`, the value follows the name. |
| `displayPercentages` | `boolean` | no | `false` | Label each step with its share of all steps’ total instead of its value. |
| `shrinkAnchor` | `"top" \| "middle" \| "bottom" \| "none"` | no | `"middle"` | Where each step narrows towards the next. `"none"` draws straight-sided bars. |
| `shrinkFraction` | `number` | no | `1` | How much of each step narrows, from 0 (none of it) to 1 (all of it). |
| `title` | `string` | no |  | The card’s title. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |
| `hideMenu` | `boolean` | no | `false` | Hide the card’s header: the title, description and menu. |
| `menuOptions` | `("csv" \| "xlsx" \| "png" \| "maximize")[]` | no | `["csv", "xlsx", "png", "maximize"]` | Which entries the card menu offers. Pass `[]` for none. |

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. [Field options](/docs/describing-your-data.md#field-options) describes them.
