Ripl

Appearance

Gauge Chart ​

The Gauge Chart puts one number on a semi-circular arc, filled from min to max in proportion to value. Use it when a dashboard tile needs one reading against a known range — utilization, progress to target, a health score. ticks and tickLabels place graduations around the arc, format and tickFormat control how the number and the graduations read, and color, trackColor and label set the rest. The arc sweeps to its new position whenever the value changes. It works against any Ripl rendering target: Canvas, SVG or a terminal.

NOTE

For the full API, see the Charts API Reference.

Example ​

Usage ​

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

const chart = createGaugeChart('#container', {
    value: 72,
    min: 0,
    max: 100,
    label: 'Performance',
    format: v => `${v}%`,
});

// Update value
chart.update({ value: 85 });

Data Format ​

A gauge shows a single number rather than a dataset, so there is no data option — pass value directly and update it as it changes:

ts
const chart = createGaugeChart('#container', {
    value: 72,
    min: 0,
    max: 100,
});

chart.update({ value: 85 });

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
createGaugeChart('#container', {
    value: 72,
    min: 0,
    max: 100,
    label: 'Utilisation',
    color: '#6dd5b1',
    trackColor: '#e5e7eb',
    ticks: 5,
    tickLabels: true,
    // `format` styles the central value; `tickFormat` styles the tick labels around the arc.
    format: 'number',
    tickFormat: v => `${v}%`,
});

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 the value arc is clicked.
chart.on('valueclick', event => console.log(event.data)); // event.data: GaugeChartValueEvent
// Emitted when the pointer enters the value arc.
chart.on('valueenter', event => console.log(event.data)); // event.data: GaugeChartValueEvent
// Emitted when the pointer leaves the value arc.
chart.on('valueleave', event => console.log(event.data)); // event.data: GaugeChartValueEvent