Getting Started with Charts

@ripl/charts is a set of interactive chart types built on the Ripl core rendering engine. Every chart animates its data transitions, emits pointer events, resizes with its container, and draws through the same Context, so one chart definition renders to Canvas or SVG.

NOTE

For the full API, see the Charts API Reference.

Installation

bash

npm install @ripl/charts

TIP

@ripl/charts depends on @ripl/core, which is installed automatically. You don't need to install it separately.

Your First Chart

Every chart follows the same pattern:

Import the factory function for the chart type
Call it with a target (CSS selector, HTMLElement, or Context) and an options object
Update the chart reactively via chart.update(options)

import {
    createBarChart,
} from '@ripl/charts';

const chart = createBarChart('#chart-container', {
    data: [
        {
            month: 'Jan',
            sales: 120,
            costs: 80,
        },
        {
            month: 'Feb',
            sales: 200,
            costs: 110,
        },
        {
            month: 'Mar',
            sales: 150,
            costs: 90,
        },
    ],
    key: 'month',
    series: [
        {
            id: 'sales',
            value: 'sales',
            label: 'Sales',
        },
        {
            id: 'costs',
            value: 'costs',
            label: 'Costs',
        },
    ],
});

That's all it takes to get a fully interactive bar chart, complete with animated entry, hover tooltips, and axis labels.

Updating Data

Call chart.update() with partial options to update the chart in place. Changes animate: new data points enter, removed points exit, and existing points transition to their new positions.

chart.update({
    data: [
        {
            month: 'Jan',
            sales: 180,
            costs: 100,
        },
        {
            month: 'Feb',
            sales: 220,
            costs: 130,
        },
        {
            month: 'Mar',
            sales: 170,
            costs: 95,
        },
        {
            month: 'Apr',
            sales: 300,
            costs: 150,
        },
    ],
});

Any option can be updated this way, not only the data:

chart.update({ stacked: true });
chart.update({ orientation: 'horizontal' });
chart.update({ legend: true });

Common Options

All charts extend BaseChartOptions and share these core options:

Option	Type	Default	Description
`padding`	`PaddingInput`	`16`	Space reserved around the chart area: a number for every edge, a `[top, right, bottom, left]` tuple, or a partial per-edge object
`animation`	`boolean \| Partial<ChartAnimationOptions>`	`{ enabled: true, duration: 1000, ease: 'easeOutCubic' }`	Animation toggle or configuration
`title`	`string \| Partial<ChartTitleOptions>`	—	Chart title text or configuration
`autoRender`	`boolean`	`true`	Automatically render on creation and update
`theme`	`string \| Theme`	module default	A registered theme name (`'light'`/`'dark'`/`'auto'`) or a `Theme` object
`description`	`string`	title text	Accessible description announced by screen readers

Most chart types also support these feature options:

Option	Type	Default	Description
`axis`	`boolean \| ChartAxisOptions`	`true`	Show/configure x and y axes
`grid`	`boolean \| ChartGridOptions`	`true`	Show/configure background grid lines
`tooltip`	`boolean \| ChartTooltipOptions`	`true`	Show/configure hover tooltips
`legend`	`boolean \| ChartLegendOptions`	auto	Show/configure series legend (shown by default for charts with more than one series/segment, at the bottom)
`crosshair`	`boolean \| ChartCrosshairOptions`	varies	Show/configure crosshair tracking

See Shared Options for a complete reference on each of these, and each chart's own page for the full, generated list of every option it accepts.

SVG Rendering

Charts render to Canvas by default. To use SVG, pass an SVG context as the target:

import {
    createBarChart,
} from '@ripl/charts';

import {
    createContext,
} from '@ripl/svg';

const svgContext = createContext('#chart-container');

const chart = createBarChart(svgContext, {
    data: [/* ... */],
    key: 'month',
    series: [/* ... */],
});

Destroying a Chart

Call destroy() to clean up the chart, its scene, renderer, and all event subscriptions:

chart.destroy();

Available Charts

Cartesian

Chart	Factory	Description
Line	`createLineChart`	One or more series as lines, with 13 interpolation modes per series, optional markers, dual y-axes, crosshair, grid and legend.
Bar	`createBarChart`	Grouped, stacked or 100% stacked bars, vertical or horizontal, with rounded corners, value labels, tooltips and a legend.
Area	`createAreaChart`	Filled bands beneath line series, stacked or overlaid, with per-series fill opacity, crosshair, grid and tooltips.
Trend	`createTrendChart`	Line, bar and area series mixed on shared axes, with per-type stacking and an overview strip for windowing the x-range.
Scatter	`createScatterChart`	Points across x and y for two continuous measures, with optional size-encoded bubbles, dual-axis crosshair and pan-zoom.
Stock	`createStockChart`	OHLC candlesticks with a labeled volume sub-chart, separate up and down colors, crosshair, annotations and pan-zoom.
Histogram	`createHistogramChart`	The distribution of a numeric field, binned into bars over a continuous value axis with nice bins or explicit thresholds.
Box Plot	`createBoxPlotChart`	An interquartile box, median, 1.5x IQR whiskers and outliers per category, from the shared boxplotStats transform.

Radial & Polar

Chart	Factory	Description
Pie/Donut	`createPieChart`	Proportions as angular slices, with an inner radius for a donut, constant-width slice gaps, labels and hover dimming.
Polar Area	`createPolarAreaChart`	Equal-angle segments whose radius encodes value, over configurable value rings, with labels and a legend.
Polar Scatter	`createPolarScatterChart`	Points on a circular grid where angle and radius each encode a variable, and a third can drive marker size.
Radial Bar	`createRadialBarChart`	Concentric rings whose arcs sweep to each value, with a faint track behind, configurable angular range and rounded caps.
Radar	`createRadarChart`	One polygon per series across shared category spokes, with configurable grid rings, markers, labels and a legend.
Gauge	`createGaugeChart`	A single value on a semi-circular arc between a min and max, with tick marks, tick labels and a custom value formatter.

Hierarchical

Chart	Factory	Description
Treemap	`createTreemapChart`	A total tiled into nested rectangles whose areas encode value, with configurable gaps, corner radius and automatic labels.
Packed Circle	`createPackedCircleChart`	Circles whose areas encode value, packed tightly without overlap inside one containing circle, with labels on the larger ones.
Sunburst	`createSunburstChart`	A tree as concentric rings, one ring per depth level, where each arc's width is its share of its parent.

Network & Flow

Chart	Factory	Description
Funnel	`createFunnelChart`	Ordered stages as progressively narrowing bars, so each step's drop-off is the width it loses. Gaps and corners are configurable.
Sankey	`createSankeyChart`	Weighted flows between nodes as proportional links, laid out automatically. For energy flows, budgets and user journeys.
Force-Directed	`createForceDirectedChart`	A node-link graph laid out by a deterministic physics simulation, with tunable charge, link distance and centering.
Arc Diagram	`createArcDiagramChart`	Nodes along one axis joined by arcs whose thickness encodes link weight, horizontally or vertically, sized by degree.
Chord	`createChordChart`	Group-to-group flows from a square matrix as ribbons inside a ring of arcs, with hover dimming and configurable gaps.

Specialized

Chart	Factory	Description
Heatmap	`createHeatmapChart`	One value across two categorical axes as colored cells, with a configurable gradient and a continuous color legend.
Gantt	`createGanttChart`	Tasks as bars on a time axis, with progress overlays, finish-to-start dependency connectors, a today marker and tooltips.
Realtime	`createRealtimeChart`	A sliding window of streaming values that scrolls as you push new ones, with a fixed window size and optional area fills.

Next Steps

Shared Options: the full reference for axis, legend, tooltip, grid, and crosshair configuration
Bar Chart: grouped, stacked and horizontal bars, with every shared option in play
Theming: light/dark/colorblind themes and custom palettes
Annotations: reference lines, bands, and point markers
Panning & Zooming: interactive navigation and the overview strip
Custom Charts: build your own chart type on the Chart base class
Charts API Reference: full TypeScript API documentation

Getting Started with Charts ​

Installation ​

Your First Chart ​

Updating Data ​

Common Options ​

SVG Rendering ​

Destroying a Chart ​

Available Charts ​