d3-funnel is an extensible, open-source JavaScript library for rendering funnel charts using the D3.js library.
d3-funnel is focused on providing practical and visually appealing funnels through a variety of customization options. Check out the examples page to get a showcasing of the several possible options.
To install this library, simply include both D3.js v4.x and D3Funnel:
<script src="/path/to/d3.v4.js"></script>
<script src="/path/to/dist/d3-funnel.js"></script>
Alternatively, if you are using Webpack or Browserify, you can install the npm
package and import
the module. This will include a compatible version of
D3.js for you:
npm install d3-funnel --save
import D3Funnel from 'd3-funnel';
To use this library, you must create a container element and instantiate a new funnel chart. By default, the chart will assume the width and height of the parent container:
<div id="funnel"></div>
<script>
const data = [
{ label: 'Inquiries', value: 5000 },
{ label: 'Applicants', value: 2500 },
{ label: 'Admits', value: 500 },
{ label: 'Deposits', value: 200 },
];
const options = {
block: {
dynamicHeight: true,
minHeight: 15,
},
};
const chart = new D3Funnel('#funnel');
chart.draw(data, options);
</script>
Option | Description | Type | Default |
---|---|---|---|
chart.width |
The width of the chart in pixels or a percentage. | mixed | Container's width |
chart.height |
The height of the chart in pixels or a percentage. | mixed | Container's height |
chart.bottomWidth |
The percent of total width the bottom should be. | number | 1 / 3 |
chart.bottomPinch |
How many blocks to pinch on the bottom to create a funnel "neck". | number | 0 |
chart.inverted |
Whether the funnel direction is inverted (like a pyramid). | bool | false |
chart.animate |
The load animation speed in milliseconds. | number | 0 (disabled) |
chart.curve.enabled |
Whether the funnel is curved. | bool | false |
chart.curve.height |
The curvature amount. | number | 20 |
chart.totalCount |
Override the total count used in ratio calculations. | number | null |
block.dynamicHeight |
Whether the block heights are proportional to their weight. | bool | false |
block.dynamicSlope |
Whether the block widths are proportional to their value decrease. | bool | false |
block.barOverlay |
Whether the blocks have bar chart overlays proportional to its weight. | bool | false |
block.fill.scale |
The background color scale as an array or function. | mixed | d3.schemeCategory10 |
block.fill.type |
Either 'solid' or 'gradient' . |
string | 'solid' |
block.minHeight |
The minimum pixel height of a block. | number | 0 |
block.highlight |
Whether the blocks are highlighted on hover. | bool | false |
label.enabled |
Whether the block labels should be displayed. | bool | true |
label.fontFamily |
Any valid font family for the labels. | string | null |
label.fontSize |
Any valid font size for the labels. | string | '14px' |
label.fill |
Any valid hex color for the label color. | string | '#fff' |
label.format |
Either function(label, value) or a format string. See below. |
mixed | '{l}: {f}' |
tooltip.enabled |
Whether tooltips should be enabled on hover. | bool | false |
tooltip.format |
Either function(label, value) or a format string. See below. |
mixed | '{l}: {f}' |
events.click.block |
Callback function(data) for when a block is clicked. |
function | null |
The option label.format
can either be a function or a string. The following
keys will be substituted by the string formatter:
Key | Description |
---|---|
'{l}' |
The block's supplied label. |
'{v}' |
The block's raw value. |
'{f}' |
The block's formatted value. |
Block-based events are passed a data
object containing the following elements:
Key | Type | Description |
---|---|---|
index | number | The index of the block. |
node | object | The DOM node of the block. |
value | number | The numerical value. |
fill | string | The background color. |
label.raw | string | The unformatted label. |
label.formatted | string | The result of options.label.format . |
label.color | string | The label color. |
Example:
{
index: 0,
node: { ... },
value: 150,
fill: '#c33',
label: {
raw: 'Visitors',
formatted: 'Visitors: 150',
color: '#fff',
},
},
You may wish to override the default chart options. For example, you may wish
for every funnel to have proportional heights. To do this, simply modify the
D3Funnel.defaults
property:
D3Funnel.defaults.block.dynamicHeight = true;
Should you wish to override multiple properties at a time, you may consider
using lodash's _.merge
or jQuery's $.extend
:
D3Funnel.defaults = _.merge(D3Funnel.defaults, {
block: {
dynamicHeight: true,
fill: {
type: 'gradient',
},
},
label: {
format: '{l}: ${f}',
},
});
In the examples above, both label
and value
were just to describe a block
within the funnel. A complete listing of the available options is included
below:
Option | Type | Description | Example |
---|---|---|---|
label | mixed | Required. The label to associate with the block. | 'Students' |
value | number | Required. The value (or count) to associate with the block. | 500 |
backgroundColor | string | A row-level override for block.fill.scale . Hex only. |
'#008080' |
formattedValue | mixed | A row-level override for label.format . |
'USD: $150' |
hideLabel | bool | Whether to hide the formatted label for this block. | true |
labelColor | string | A row-level override for label.fill . Hex only. |
'#333' |
Additional methods beyond draw()
are accessible after instantiating the chart:
Method | Description |
---|---|
destroy() |
Removes the funnel and its events from the DOM. |
MIT license.