Skip to main content

Funnel chart

A funnel chart shows how a value attrits through ordered stages: one bar per stage, widths proportional to the stage values, with trapezoidal connectors between them making the drop-off explicit.

SELECT kuva_render(to_json({
'title': 'CONSORT flow',
'series': [{
'type': 'funnel',
'stages': stages
}]
})) AS chart
FROM (
SELECT list({'label': stage, 'value': n_screened}) AS stages
FROM read_csv_auto('{{DFK_BASE_URL}}data/funnel.tsv')
);

Stages are drawn top to bottom in list order, so the order you aggregate is the order of the funnel. The first stage is the reference: every percentage and conversion rate on the chart is measured against it.

Colour modes​

color_modeBars
"uniform"All the same colour (default)
"by_stage"A distinct palette colour per stage
"gradient"Progressively darker from top to bottom

A stage's own color overrides the mode for that bar, which is how you highlight one specific step.

SELECT kuva_render(to_json({
'title': 'Gradient',
'series': [{
'type': 'funnel',
'stages': stages,
'color_mode': 'gradient',
'show_percents': true
}]
})) AS chart
FROM (
SELECT list({'label': stage, 'value': n_screened}) AS stages
FROM read_csv_auto('{{DFK_BASE_URL}}data/funnel.tsv')
);

Horizontal orientation​

orientation: "horizontal" turns the funnel on its side, which suits short stage labels and wide figures.

SELECT kuva_render(to_json({
'title': 'Horizontal funnel',
'series': [{
'type': 'funnel',
'stages': stages,
'orientation': 'horizontal',
'color_mode': 'by_stage',
'show_percents': true
}]
})) AS chart
FROM (
SELECT list({'label': stage, 'value': n_screened}) AS stages
FROM read_csv_auto('{{DFK_BASE_URL}}data/funnel.tsv')
);

Diverging mode​

mirror adds a second set of stages back to back with the first — the classic treatment-vs-control comparison. left_label and right_label name the two sides.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/funnel.tsv'))
SELECT kuva_render(to_json({
'title': 'Treatment vs control',
'series': [{
'type': 'funnel',
'stages': (SELECT list({'label': stage, 'value': n_screened}) FROM d),
'mirror': (SELECT list({'label': stage, 'value': n_placebo}) FROM d),
'left_label': 'Treatment',
'right_label': 'Control',
'color_mode': 'by_stage'
}]
})) AS chart;

Both sides share the same stage list, so the two arms line up row for row. Give them different numbers of stages and the shorter one simply runs out.

Labels and connectors​

FieldDefaultWhat it sets
show_valuestrueThe absolute value on each bar
show_percentsfalseThe share of the first stage, next to the value
show_conversiontrueThe step-to-step rate in the connector areas
show_connectorstrueDraw the trapezoidal connectors at all
connector_opacity0.4Connector fill opacity
stage_gap4Gap between adjacent bars, in pixels

Turning the values off and leaving the conversion rates on gives a minimal funnel that reads as pure percentages:

SELECT kuva_render(to_json({
'title': 'Conversion rates only',
'series': [{
'type': 'funnel',
'stages': stages,
'show_values': false,
'show_percents': false,
'show_conversion': true,
'color_mode': 'gradient',
'stage_gap': 8
}]
})) AS chart
FROM (
SELECT list({'label': stage, 'value': n_screened}) AS stages
FROM read_csv_auto('{{DFK_BASE_URL}}data/funnel.tsv')
);

Fields​

FieldTypeWhat it sets
stagesstage[]Required. One entry per stage, in order: {label, value, color?}.
mirrorstage[]A second set of stages drawn back to back — diverging mode.
left_label / right_labelstringSide labels in diverging mode.
orientationstring"vertical" (default) or "horizontal".
color_modestring"uniform" (default) · "by_stage" · "gradient".
show_connectorsbooleanDraw the trapezoidal connectors (default on).
connector_opacitynumberConnector fill opacity (default 0.4).
show_valuesbooleanValue label on each bar (default on).
show_percentsbooleanPercentage-of-first-stage label (default off).
show_conversionbooleanStep-to-step conversion rate (default on).
stage_gapnumberGap between adjacent bars, in pixels (default 4).
legendstringAny non-empty value turns the legend on.

Notes​

  • stages must not be empty, and the values must be ordered widest first — a later stage larger than its predecessor draws a funnel that widens, which is usually a data error rather than a chart style.
  • All-zero stages are an error (there is no reference width to scale against).
  • show_percents measures against the first stage, while show_conversion measures against the previous one — they answer different questions.
  • A stage's color wins over color_mode.

See also​