intelogie/d3-funnel

D3 Funnel

, _(*1)

D3Funnel is an extensible, open-source JavaScript library for rendering funnel charts using the D3.js library., _(*2)

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., _(*3)

Installation

To install this library, simply include both D3.js v4.x and D3Funnel:, _(*4)

``` html , <sub>(*5)</sub>

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, <sub>(*6)</sub>

``` javascript
// 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:, <sub>(*7)</sub>

``` html, <sub>(*8)</sub>

## 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.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)`, an array, or a format string. See below. | mixed    | `'{l}: {f}'`            |
| `events.click.block`   | Callback `function(data)` 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. |

### 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:

``` javascript
{
    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:, <sub>(*9)</sub>

``` javascript D3Funnel.defaults.block.dynamicHeight = true;, <sub>(*10)</sub>

Should you wish to override multiple properties at a time, you may consider
using [lodash's][lodash-merge] `_.merge` or [jQuery's][jquery-extend] `$.extend`:

``` javascript
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:, <sub>(*11)</sub>

Advanced Data

You can specify colors to override block.fill.scale and label.fill for any data point (hex only):, <sub>(*12)</sub>

``` javascript var data = [ ['Teal', 12000, '#008080', '#080800'], ['Byzantium', 4000, '#702963'], ['Persimmon', 2500, '#ff634d', '#6f34fd'], ['Azure', 1500, '#007fff', '#07fff0'], // Background ---^ ^--- Label ];, <sub>(*13)</sub>

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

``` javascript
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., <sub>(*14)</sub>