d3-funnel

D3 Funnel

D3Funnel is an extensible, open-source JavaScript library for rendering funnel charts using the D3.js library.

D3Funnel 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 and D3Funnel:

<script src="/path/to/d3.min.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 require the module:

npm install d3-funnel --save

var D3Funnel = require('d3-funnel')

Usage

To use this library, you must create a container element and instantiate a new funnel chart:

<div id="funnel"></div>

<script>
    var data = [
        ['Plants',     5000],
        ['Flowers',    2500],
        ['Perennials', 200],
        ['Roses',      50],
    ];
    var options = {};

    var chart = new D3Funnel('#funnel');
    chart.draw(data, options);
</script>

Options

Option	Description	Type	Default
chart.width	The pixel width of the chart.	int	Container's width
chart.height	The pixel height of the chart.	int	Container's height
chart.bottomWidth	The percent of total width the bottom should be.	float	1 / 3
chart.bottomPinch	How many blocks to pinch on the bottom to create a "neck".	int	0
chart.inverted	Whether the funnel is inverted (like a pyramid).	bool	false
chart.animate	The load animation speed in milliseconds.	int/bool	false
chart.curve.enabled	Whether the funnel is curved.	bool	false
chart.curve.height	The curvature amount.	int	20
block.dynamicHeight	Whether the block heights are proportional to its weight.	bool	false
block.fill.scale	The block background color scale. Expects an index and returns a color.	function/array	d3.scale.category10()
block.fill.type	Either 'solid' or 'gradient'.	string	'solid'
block.minHeight	The minimum pixel height of a block.	int/bool	false
block.highlight	Whether the blocks are highlighted on hover.	bool	false
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}'
events.click.block	Callback for when a block is clicked.	function	null

Label 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.

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, simplify 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, {
	chart: {
		dynamicHeight: true,
		animate: 200,
	},
	label: {
		format: '{l}: ${f}',
	},
});

API

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

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

Advanced Data

You can specify colors to override block.fill.scale and label.fill for any data point (hex only):

var data = [
    ['Teal',      12000, '#008080' '#080800'],
    ['Byzantium', 4000,  '#702963'],
    ['Persimmon', 2500,  '#ff634d' '#6f34fd'],
    ['Azure',     1500,  '#007fff' '#07fff0'],
    //         Background ---^         ^--- Label
];

If you want to pass formatted values to be shown in the funnel, pass in an array containing the value and formatted value:

var data = [
    ['Teal',      [12000, 'USD 12,000']],
    ['Byzantium', [4000,  'USD 4,000']],
    ['Persimmon', [2500,  'USD 2,500']],
    ['Azure',     [1500,  'USD 1,500']],
];

License

MIT license.

Changelog

v0.7.0 (2015-10-04)

D3Funnel v0.7 is a backwards-incompatible release that resolves some outstanding bugs, standardizes several option names and formats, and introduces a few new features.

No new features will be added to the v0.6 series, but minor patches will be available for a few months.

Behavior Changes

• [#29]: Dynamic block heights are no longer determined by their weighted area, but by their weighted height
  • Heights determined by weighted area: http://jsfiddle.net/zq4L82kv/2/ (legacy v0.6.x)
  • Heights determined by weighted height: http://jsfiddle.net/bawv6m0j/3/ (v0.7+)

New Features

• [#9]: Block can now have their color scale specified in addition to data points
• [#34]: Default options are now statically available and overridable

Bug Fixes

• [#25]: Fix issues with isInverted and dynamicArea producing odd pyramids
• [#32]: Fix issue where pinched blocks were not having the same width as bottomWidth