Funnel

A funnel shows a count moving through stages in order. Each stage is a band. The width comes from the value. The first band sits at the top, and the next stage sits under it.

When to use it

Use a funnel when the question is how many people or items remain at each step. Visit, signup, activate, trial, pay is that chart. From pitch to liftoff is the same idea: a queue that narrows.

A bar compares categories. The categories do not have to be a sequence, and the width is not a drop from the previous bar. A waterfall is signed steps between totals, including gains. A funnel value is a size at a stage. Negatives are drawn as zero.

A handful of stages stays readable. Signup funnel has five. From enquiry to a seat has four. A long list of names, with no order that matters, is a bar.

Funnel, bar, and waterfall

All three can show a value per name. The encoding is what changes.

type: "funnel" keeps data order and sets the width from the value. The largest value is the full width. A later stage can be wider than an earlier one when its value is larger. The chart does not sort.

type: "bar" is the comparison. mark.orientation can turn those bars horizontal. That key does not apply to a funnel. Setting it warns CK3010.

type: "waterfall" draws a delta, and a total row is a full bar. A funnel has no total row. Each stage is its own value.

Data

Each row is one stage and one number. Point encoding.x at the stage and encoding.y at the number. Signup funnel uses stage and count. From enquiry to a seat uses stage and people.

Rows are drawn from top to bottom in the order you pass them. mark.sort is a pie and donut key. On a funnel it warns CK3010 and the order stays put.

A missing number is skipped. A negative number is drawn as zero. The stage name still has a place in the column.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest funnel. version, type, and a11y.alt are required. The body is one tapering shape and the values are labeled, so mark can be omitted.

spec.json
{
  "version": "1",
  "type": "funnel",
  "data": [
    {
      "stage": "Visit",
      "count": 80
    },
    {
      "stage": "Start",
      "count": 40
    },
    {
      "stage": "Pay",
      "count": 12
    }
  ],
  "encoding": {
    "x": "stage",
    "y": "count"
  },
  "a11y": {
    "alt": "12 of 80 visits pay."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/funnelBundle@chartkitdev/core/extraFamilyStatistical
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing funnel specs. Signup funnel is the core example, five stages and no legend. From pitch to liftoff names each stage in a legend. From enquiry to a seat sets the trapezoid shape explicitly.

Shape

mark.shape is the geometry. Omit it, or set trapezoid, and each stage shares its bottom edge with the next stage. The width tapers with the value, so the body reads as one piece.

bar draws a centered rounded bar for each stage. The width is still the value. The stages stay in data order, with a gap between bars. This is still type: "funnel". A comparison chart is type: "bar".

mark.shape
{
  "mark": { "shape": "bar" }
}

Labels

The stage name is always drawn. mark.labels draws the value beside it. Omit the key, or set true, and the number is shown. After the first stage the line also shows that stage as a share of the previous one. false hides the number and the share. The name stays.

mark.labels
{
  "mark": { "labels": false }
}

mark.labelFormat formats that number. Change it in the playground. Turning labels off and on again puts the example's format back. An example that omitted mark.labels gets the key removed, so the default stays on.

Legend

A funnel omits the legend. The stage names are already in the column. Set legend to true, or to an object, and the stages are listed again. false hides that list. legend.position is top, right, bottom, or left. When the position is omitted, the list sits on top. From pitch to liftoff and From enquiry to a seat set top.

Asking for a legend also gives each stage its own color. With no legend and no encoding.color, the stages share one color.

legend.position
{
  "legend": { "position": "top" }
}

Tooltip

tooltip is on for a funnel when the key is omitted. Hovering a stage shows its name, its value, and, after the first stage, its share of the previous stage. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back.

The rest of the spec

mark.gap opens a slit between trapezoid stages, as a fraction of the band. Omit it and the body stays one piece. encoding.color can name a field when you want a color that does not depend on the legend. Theme presets live on the playground, with the full option list.