Ripl

Appearance

Pie Chart ​

The Pie Chart splits a circle into slices whose angles are each category's share of the total. Use it when the parts sum to a meaningful whole and there are few enough of them to tell apart — a handful of categories, not thirty. innerRadius turns it into a donut, padWidth sets a constant-width gap that holds its width right to the center, and labels, colorBy and format handle the rest. Slices are filled with a translucent tint of their series color; hover one for a tooltip and the others dim. Entry, exit and reorder are all animated. Canvas is the default target; pass an SVG or terminal context to draw the same chart elsewhere.

NOTE

For the full API, see the Charts API Reference.

Example ​

Usage ​

ts
import {
    createPieChart,
} from '@ripl/charts';

const chart = createPieChart('#container', {
    key: 'id',
    value: 'value',
    label: 'label',
    data: [
        {
            id: '1',
            label: 'Australia',
            value: 55,
        },
        {
            id: '2',
            label: 'Poland',
            value: 21,
        },
        {
            id: '3',
            label: 'South Africa',
            value: 185,
        },
    ],
});

Data Format ​

Each item needs a unique key, a numeric value, and a display label:

ts
const data = [
    {
        id: 'au',
        label: 'Australia',
        value: 55,
    },
    {
        id: 'pl',
        label: 'Poland',
        value: 21,
    },
    {
        id: 'za',
        label: 'South Africa',
        value: 185,
    },
];

The key, value, and label options map to fields in each data item.

Variants ​

Donut ​

Set innerRadius (0–1, as a fraction of the outer radius) to create a donut chart:

ts
createPieChart('#container', {
    data,
    key: 'id',
    value: 'value',
    label: 'label',
    innerRadius: 0.5,
});

Per-slice colors ​

Drive slice colors from the data instead of the palette:

ts
createPieChart('#container', {
    data,
    key: 'id',
    value: 'value',
    label: 'label',
    colorBy: 'color',
});

Options ​

A full configuration for this chart. The options every chart shares — padding, title, animation, theme and the rest — behave the same everywhere and are documented on Shared Options.

ts
createPieChart('#container', {
    data,
    key: 'browser',
    value: 'share',
    label: 'browser',
    colorBy: 'browser',
    // Non-zero turns the pie into a donut. A value of 1 or less is a fraction of the outer
    // radius; anything larger is read as absolute pixels.
    innerRadius: 60,
    // Segments are separated by a gap of this constant width, in pixels.
    padWidth: 2,
    labels: 'outside',
    legend: { position: 'right' },
    format: 'percentage',
});

Events ​

Subscribe with chart.on(...). A handler receives an Event object, not the payload directly — the payload is on event.data, and carries the interacted datum plus its { x, y } anchor in chart pixels. event.target and event.stopPropagation() are also available.

ts
// Emitted when a segment is clicked.
chart.on('segmentclick', event => console.log(event.data)); // event.data: PieChartSegmentEvent
// Emitted when the pointer enters a segment.
chart.on('segmententer', event => console.log(event.data)); // event.data: PieChartSegmentEvent
// Emitted when the pointer leaves a segment.
chart.on('segmentleave', event => console.log(event.data)); // event.data: PieChartSegmentEvent