Ripl

Appearance

Histogram Chart ​

The Histogram Chart bins a numeric field and draws each bin as a bar on a continuous value axis against a frequency axis. Its job is the shape of a distribution — where the mass sits, how long the tail runs, whether it is one peak or two — not a comparison of named categories. Binning uses the shared bin transform: bins asks for a bin count and gets nice round boundaries, or thresholds sets the cut points exactly. borderRadius, color and format handle the finish, and bars animate on entry, update and exit as the binning changes. Being a cartesian chart it also takes a crosshair, grid and annotations, on a Canvas, SVG or terminal target.

NOTE

For the full API, see the Charts API Reference.

Example ​

Usage ​

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

const chart = createHistogramChart('#container', {
    data: [/* ... */],
    value: 'amount',
    bins: 12,
});

Data Format ​

Each item contributes one numeric value, read via the value accessor (a field name or a function). The chart bins those values itself, so no pre-aggregation is required.

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
createHistogramChart('#container', {
    data,
    value: 'duration',
    // Target bin count — the binner treats it as a hint and rounds to a readable step.
    // `thresholds` below is the alternative, and wins when both are given.
    bins: 20,
    color: '#7cacf8',
    borderRadius: 2,
    format: 'number',
});

To place the bin edges yourself — uneven buckets, or a scale that has to match another chart — pass thresholds instead of bins:

ts
createHistogramChart('#container', {
    data,
    value: 'duration',
    // n edges produce n - 1 bins: 0–50, 50–100, 100–250, 250–500.
    thresholds: [0, 50, 100, 250, 500],
});

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 bin bar is clicked.
chart.on('binclick', event => console.log(event.data)); // event.data: HistogramBinEvent
// Emitted when the pointer enters a bin bar.
chart.on('binenter', event => console.log(event.data)); // event.data: HistogramBinEvent
// Emitted when the pointer leaves a bin bar.
chart.on('binleave', event => console.log(event.data)); // event.data: HistogramBinEvent