d3-funnel

d3-funnel

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.

Installation

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';

Usage

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>

Options

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

Label/Tooltip Format

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.

Event Data

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',
    },
},

Overriding Defaults

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}',
    },
});

Advanced Data

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'

API

Additional methods beyond draw() are accessible after instantiating the chart:

Method	Description
destroy()	Removes the funnel and its events from the DOM.

License

MIT license.