intelogie/d3-funnel

There is no license information available for the latest version (dev-master) of this package.

dev-master 2017-05-08 20:15 UTC

Unknown License

README

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 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 require or import the module. This will include a compatible version of D3.js for you:

npm install d3-funnel --save

// CommonJS
var D3Funnel = require('d3-funnel');

// ES6
import D3Funnel from 'd3-funnel';

Usage

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

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

<script>
    const data = [
        ['Plants',     5000],
        ['Flowers',    2500],
        ['Perennials', 200],
        ['Roses',      50],
    ];
    const options = { block: { dynamicHeight: true } };

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

Options

Label Format

The option label.format can either be a function or a string. The following keys will be substituted by the string formatter:

Event Data

Block-based events are passed a data object containing the following elements:

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

API

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

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

In addition to using label.format, you can also pass formatted values in an array:

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.