Skip to content
D3plus

Funnel

Creates a funnel chart from an array of data: one stage per row, in data order unless sort reorders them, drawn as a centered bar whose width encodes its value, with necks joining consecutive stages. Labels show each stage’s name and value, plus any conversion rates conversion asks for; tooltips show the conversion from the first and the previous stage.

Basic example

Section titled “Basic example”

Each row is a stage, drawn in data order as a centered bar whose width encodes its value. Necks join consecutive stages; a label goes inside its stage when it fits, otherwise beside it.

The gap between consecutive stages, as a fraction (0–1) of each stage's slot; the necks fill it.

Whether to fill the gap between consecutive stages with a neck joining their widths. A neck takes its stage's shapeConfig.texture and shapeConfig.backgroundImage; see connectorConfig to override them.

orient

The direction stages run: "vertical" (top to bottom, widths across) or "horizontal" (left to right, heights across).

Conversion rates

Section titled “Conversion rates”

conversion adds each stage’s conversion rate to its label: "first" (its share of the first stage), "previous" (its share of the stage before it), or "both". Tooltips always show both rates.

Which conversion rates each stage's label shows beneath its value: "first" (its value as a share of the first stage's), "previous" (as a share of the stage before it), "both" (or true), or false for none. Tooltips always show both.

Straight sided

Section titled “Straight sided”

taper narrows each stage from its own width to the next stage’s, drawing a continuous straight-sided funnel instead of flat bars.

Whether each stage narrows from its own width to the next stage's, drawing a continuous straight- or smooth-sided funnel instead of flat bars. The last stage keeps its own width.

The gap between consecutive stages, as a fraction (0–1) of each stage's slot; the necks fill it.

Whether to fill the gap between consecutive stages with a neck joining their widths. A neck takes its stage's shapeConfig.texture and shapeConfig.backgroundImage; see connectorConfig to override them.

Smooth funnel

Section titled “Smooth funnel”

curve("smooth") bends the funnel’s sides through each stage’s width without overshooting. Without taper, it curves only the necks between stages.

curve

How the funnel's width changes from one stage to the next: "linear" (straight sides) or "smooth" (curved sides that ease into each stage).

Whether each stage narrows from its own width to the next stage's, drawing a continuous straight- or smooth-sided funnel instead of flat bars. The last stage keeps its own width.

The gap between consecutive stages, as a fraction (0–1) of each stage's slot; the necks fill it.

Horizontal

Section titled “Horizontal”

orient("horizontal") runs the stages left to right, with each stage’s height encoding its value. Labels that don’t fit inside a stage go below it.

orient

The direction stages run: "vertical" (top to bottom, widths across) or "horizontal" (left to right, heights across).

Which conversion rates each stage's label shows beneath its value: "first" (its value as a share of the first stage's), "previous" (as a share of the stage before it), "both" (or true), or false for none. Tooltips always show both.

Colored by phase

Section titled “Colored by phase”

With several groupBy levels, each row of the last level is a stage and the stages take their color from the first level, which the legend names. connectorConfig paints the necks.

groupBy

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

["phase", "stage"]

Small multiples

Section titled “Small multiples”

facet draws one funnel per channel. By default each panel is sized to its own first stage, so conversion reads the same way in every panel.

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

Which conversion rates each stage's label shows beneath its value: "first" (its value as a share of the first stage's), "previous" (as a share of the stage before it), "both" (or true), or false for none. Tooltips always show both.

Shared width scale

Section titled “Shared width scale”

With facetConfig: {scales: "shared"}, every panel measures its stages against the widest stage across all panels, so the panels compare volume as well as shape.

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

Sorted stages

Section titled “Sorted stages”

Stages draw in data order unless sort orders them, as a comparator over two rows. Conversion rates follow the drawn order, so “% of previous” compares each stage with the one above it.

Which conversion rates each stage's label shows beneath its value: "first" (its value as a share of the first stage's), "previous" (as a share of the stage before it), "both" (or true), or false for none. Tooltips always show both.

Configuration

import {Funnel} from "@d3plus/core";

Extends Viz.

activefalse | function

The active callback function for highlighting shapes.

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

connectorbooleanDefault true

Whether to fill the gap between consecutive stages with a neck joining their widths. A neck takes its stage's shapeConfig.texture and shapeConfig.backgroundImage; see connectorConfig to override them.

connectorConfigrecordDefault {opacity: 0.35}

Paint for the necks between stages (fill, opacity, stroke, strokeWidth, texture, backgroundImage, backgroundImageFit), each a value or a function of the stage the neck leads into. fill defaults to that stage's fill. A neck inherits that stage's shapeConfig.texture and shapeConfig.backgroundImage; connectorConfig.texture and connectorConfig.backgroundImage override them, and false turns either off for the necks. The image takes the neck's opacity, like its fill.

conversionboolean | "first" | "previous" | "both" | ("first" | "previous")[]Default false

Which conversion rates each stage's label shows beneath its value: "first" (its value as a share of the first stage's), "previous" (as a share of the stage before it), "both" (or true), or false for none. Tooltips always show both.

curve"linear" | "smooth"Default "linear"

How the funnel's width changes from one stage to the next: "linear" (straight sides) or "smooth" (curved sides that ease into each stage).

datastring | array.&lt;datapoint&gt; | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

facetstring | false | function

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fontFamilystring | array.&lt;string&gt;

The font family used throughout the visualization.

groupBystring | function | array.&lt;string | function&gt;

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

legendboolean | functionDefault function

Hides the legend when every stage would be its own entry (stages are labeled), including across small multiples.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

orient"vertical" | "horizontal"Default "vertical"

The direction stages run: "vertical" (top to bottom, widths across) or "horizontal" (left to right, heights across).

parentunknown

Parent config used by the wrapper.

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapeConfigd3plusconfig

Configuration object with key/value pairs applied as method calls on each shape.

sortfunction

A comparator that orders the stages, given two data rows, as (a, b) => number. Defaults to data order. Conversion rates follow the sorted order: "% of previous stage" compares each stage with the one drawn before it.

stagePaddingnumberDefault 0.3

The gap between consecutive stages, as a fraction (0–1) of each stage's slot; the necks fill it.

taperbooleanDefault false

Whether each stage narrows from its own width to the next stage's, drawing a continuous straight- or smooth-sided funnel instead of flat bars. The last stage keeps its own width.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.&lt;string | date&gt;

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

tooltipConfigtooltipconfigDefault {tbody: (d: DataPoint, i: number) => funnelTooltipRows(viz, d, i)}

Tooltip rows show each stage's value, then its share of the first and of the previous stage.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.

valuestring | functionDefault "value"

Accessor function or string key for each stage's value.

valueFormatfunctionDefault function

Formats each stage's value in its label and tooltip, as (value, datum) => string. Defaults to the locale's abbreviated number format.

zoombooleanDefault false

Zooming and panning don't help read a funnel, so they're off by default.