Shared Options

All Ripl charts extend BaseChartOptions, so padding, title, legend, tooltip, theme and animation are configured the same way everywhere; the cartesian charts extend CartesianChartOptions on top of it for axes, grid, crosshair, annotations and pan/zoom. Each feature option takes the same shorthand: true/false to toggle it with its defaults, or a partial object to override individual fields.

NOTE

For the full API, see the Chart Base & Options API Reference.

Padding

Controls the space reserved around the chart drawing area. Every option named padding — on the chart, and on the title, legend and tooltip — accepts the same PaddingInput shape: a number, a [top, right, bottom, left] tuple, or a partial per-edge object.

// A single number applies to every edge
createBarChart('#container', {
    padding: 24,
    // ...
});

// A tuple sets all four edges, clockwise from the top
createBarChart('#container', {
    padding: [16, 32, 16, 32],
    // ...
});

// An object sets individual edges; unspecified edges keep the default
createBarChart('#container', {
    padding: {
        top: 16,
        right: 32,
        bottom: 16,
        left: 32,
    },
    // ...
});

Every side defaults to 16. Supply a number to set all four edges at once, or any subset of top/right/bottom/left to override individual sides; the rest keep the default.

Property	Type	Default
`top`	`number`	`16`
`right`	`number`	`16`
`bottom`	`number`	`16`
`left`	`number`	`16`

Animation

Controls entry, update, and exit animations. Pass false to disable all animation, or customize duration and easing.

// Disable animation
chart.update({ animation: false });

// Custom duration and easing
chart.update({
    animation: {
        duration: 500,
        ease: 'easeOutQuart',
    },
});

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Toggle animations on/off
`duration`	`number`	`1000`	Base duration in milliseconds
`ease`	`string \| Ease`	`'easeOutCubic'`	Easing function name or function

The duration acts as a base value that individual chart animations scale relative to. Setting duration: 500 makes all animations twice as fast.

Title

Display a title above the chart area. Pass a string for simple text, or an options object for customization.

// Simple string
createBarChart('#container', {
    title: 'Monthly Revenue',
    // ...
});

// Custom options
createBarChart('#container', {
    title: {
        text: 'Monthly Revenue',
        font: 'bold 16px sans-serif',
        fontColor: '#333',
        padding: 12,
    },
    // ...
});

Axis

Configure the x and y axes. Pass false to hide all axes, or configure each axis individually.

createLineChart('#container', {
    axis: {
        x: {
            visible: true,
            title: 'Month',
            font: '12px sans-serif',
            fontColor: '#666',
            format: 'string',
        },
        y: {
            visible: true,
            title: 'Revenue ($)',
            position: 'left',
            format: 'number',
        },
    },
    // ...
});

X-Axis Options

Property	Type	Default	Description
`visible`	`boolean`	`true`	Show/hide the axis
`font`	`string`	`'12px sans-serif'`	Label font
`fontColor`	`string`	`'#777777'`	Label color
`title`	`string`	—	Axis title text
`format`	`'number' \| 'percentage' \| 'date' \| 'string' \| Intl.NumberFormat options \| (value) => string`	—	Label formatter
`scale`	`'linear' \| 'log' \| 'pow' \| 'sqrt' \| 'symlog'`	`'linear'`	Value-axis scale family
`nice`	`boolean \| number`	`true`	Expand the domain to tick-aligned bounds
`ticks`	`number`	`10`	Target number of ticks and grid lines
`min`	`number`	—	Explicit lower bound (overrides the data extent)
`max`	`number`	—	Explicit upper bound (overrides the data extent)
`base`	`number`	`10`	Log base (when `scale: 'log'`)
`exponent`	`number`	`1`	Power exponent (when `scale: 'pow'`)
`constant`	`number`	`1`	Linear threshold near zero (when `scale: 'symlog'`)

Y-Axis Options

Extends x-axis options with:

Property	Type	Default	Description
`position`	`'left' \| 'right'`	`'left'`	Axis position

Any number of y-axes are supported by passing an array. Each position: 'right' axis sits on the right of the plot and the rest default to the left; axes on the same side stack outward from the plot in array order. Each axis scales independently to the extent of the series bound to it:

axis: {
    y: [
        { position: 'left', title: 'Revenue', format: 'number' },
        { position: 'right', title: 'Growth %', format: 'percentage' },
    ],
}

Line, area, scatter, and bar charts all render as many y-axes as you supply; bind a series to one with the series yAxis option, naming the axis's id. Every entry needs one, so reordering the array never re-points a series:

createLineChart('#container', {
    // …
    series: [
        { id: 'revenue', label: 'Revenue', value: 'revenue', yAxis: 'revenue' },
        { id: 'growth', label: 'Growth %', value: 'growth', yAxis: 'growth' },
        { id: 'units', label: 'Units', value: 'units', yAxis: 'units' },
    ],
    axis: {
        y: [
            { id: 'revenue', title: 'Revenue ($)' },
            { id: 'growth', position: 'right', title: 'Growth %' },
            { id: 'units', position: 'left', title: 'Units' },
        ],
    },
});

NOTE

Vertical bar charts support multiple y-axes for grouped (non-stacked) series. Stacked and horizontal bars use the primary axis only, since stacked columns share one cumulative scale.

Format Types

Format	Description	Example
`'number'`	Locale-formatted number	`1,234`
`'percentage'`	Decimal to percentage	`0.5` → `50.0%`
`'date'`	Date to locale string	`Jan 1, 2024`
`'string'`	String conversion	`toString()`
`(value) => string`	Custom formatter	`v => '$' + v`

Grid

Background grid lines drawn behind the chart data.

// Toggle
createBarChart('#container', { grid: true });

// Custom
createBarChart('#container', {
    grid: {
        visible: true,
        lineColor: '#f0f0f0',
        lineWidth: 1,
        lineDash: [2, 2],
    },
});

Property	Type	Default	Description
`visible`	`boolean`	`true`	Show/hide grid
`lineColor`	`string`	`'#e5e7eb'`	Grid line color
`lineWidth`	`number`	`1`	Grid line width
`lineDash`	`number[]`	`[4, 4]`	Dash pattern

Hover tooltips displaying data values.

// Toggle
createBarChart('#container', { tooltip: false });

// Custom
createBarChart('#container', {
    tooltip: {
        visible: true,
        font: '13px monospace',
        fontColor: '#fff',
        backgroundColor: '#333',
        borderRadius: 8,
        padding: 12,
        maxWidth: 250,
        wrap: true,
    },
});

Property	Type	Default	Description
`visible`	`boolean`	`true`	Show/hide tooltips
`trigger`	`'item' \| 'axis'`	`'item'`	`'item'` shows a tooltip for the hovered mark; `'axis'` shows a shared tooltip listing every active series at the hovered position (line, area, bar, scatter)
`padding`	`number \| Partial<Padding>`	`8`	Inner padding
`font`	`string`	`'12px sans-serif'`	Text font
`fontColor`	`string`	`'#FFFFFF'`	Text color
`backgroundColor`	`string`	`'#1a1a1a'`	Background color
`borderRadius`	`number \| [tl, tr, br, bl]`	`6`	Corner radius
`maxWidth`	`number`	`200`	Maximum width
`wrap`	`boolean`	`false`	Wrap long text

NOTE

The number | [tl, tr, br, bl] | 'full' shape is the Rect family'sborderRadius. The Arc element takes a plain number instead — an annular sector has no meaningful corner order — and clamps it to half the band thickness and to what the sector's span allows.

Legend

Series legend with interactive highlighting.

// Toggle
createLineChart('#container', { legend: true });

// Position shorthand
createLineChart('#container', { legend: 'bottom' });

// Custom
createLineChart('#container', {
    legend: {
        visible: true,
        position: 'bottom',
        padding: 16,
        font: '12px sans-serif',
        fontColor: '#333',
        highlight: true,
    },
});

Property	Type	Default	Description
`visible`	`boolean`	auto	Show/hide legend. When unset, shown automatically for charts with more than one series/segment and hidden otherwise. Pass `true`/`false` to force.
`position`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Legend position
`padding`	`number \| Partial<Padding>`	`16`	Outer padding
`font`	`string`	`'11px sans-serif'`	Label font
`fontColor`	`string`	`'#333333'`	Label color
`highlight`	`boolean`	`true`	Highlight series on hover

Crosshair

Tracking crosshair that follows the pointer.

// Toggle
createLineChart('#container', { crosshair: true });

// Custom
createLineChart('#container', {
    crosshair: {
        visible: true,
        axis: 'both',
        lineColor: '#666',
        lineWidth: 1,
    },
});

Property	Type	Default	Description
`visible`	`boolean`	`true`	Show/hide crosshair
`axis`	`'x' \| 'y' \| 'both'`	`'x'`	Which axis to track
`lineColor`	`string`	`'#94a3b8'`	Line color
`lineWidth`	`number`	`1`	Line width

Input Shorthand

Every feature option accepts three input forms:

// 1. Boolean: toggle with defaults
{ grid: true }
{ tooltip: false }

// 2. String (legend only): position shorthand
{ legend: 'bottom' }

// 3. Partial object: merge with defaults
{ grid: { lineColor: '#ccc', lineDash: [] } }

Internally, each input is normalized into a fully resolved options object using the defaults listed above. Unspecified properties always fall back to their defaults.

Theme

Every chart accepts a theme, either a registered name ('light', 'dark', 'colorblind', 'auto') or a Theme object. 'auto' follows the OS prefers-color-scheme. Set a global default for all charts with setDefaultTheme.

import { createLineChart, setDefaultTheme } from '@ripl/charts';

// Per chart
createLineChart('#container', { theme: 'dark', /* … */ });

// Or globally, restyling every chart's palette and furniture
setDefaultTheme('dark');

A Theme bundles the series palette, the sequential color scheme, and the furniture colors (text/axis/grid/crosshair/legend/tooltip). The built-in lightTheme matches Ripl's historical defaults, darkTheme is tuned for a dark background, and colorBlindTheme uses the Okabe–Ito palette. See Theming for custom themes and the theme registry.

Annotations

Cartesian charts (line, area, bar, scatter) accept annotations for reference lines, shaded bands, and point markers. They're drawn over the plot and resolved through the axis scales:

createLineChart('#container', {
    // …
    annotations: [
        { axis: 'y', value: 80, label: 'Target' },        // reference line
        { type: 'band', axis: 'y', from: 60, to: 80 },    // shaded band
        { type: 'point', x: 10, y: 42, label: 'Peak' },   // marker
    ],
});

See Annotations for the full reference.

Panning & Zooming

Cartesian charts also accept navigator (in-plot wheel-zoom and drag-pan) and overview (a draggable scrub-bar strip beside the plot). See Panning & Zooming.

createLineChart('#container', {
    // …
    navigator: true,
    overview: true,
});

Accessibility

Set description for an accessible label. It applies role="img" and aria-label to the chart's rendering element (falling back to the title text). Use the 'colorblind' theme for a colorblind-safe palette.

createBarChart('#container', {
    description: 'Quarterly revenue by region',
    theme: 'colorblind',
    // …
});

Spacing

Gaps between chart elements — the axis title and its tick labels, the legend and the plot, two stacked axis bands — come from a single 8-point scale rather than per-component constants, so spacing stays consistent as components are combined. It is exported for use in custom charts:

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

SPACING.none; // 0
SPACING.xs;   // 4  — half-step, only within a single component (a legend swatch and its label)
SPACING.sm;   // 8  — tightly related elements (tick marks and their labels)
SPACING.md;   // 16 — the default gap between distinct elements, and the default chart padding
SPACING.lg;   // 24
SPACING.xl;   // 32

padding is the space around the chart and remains yours to set; the scale governs the internal gaps the layout inserts.

Events

Every chart is an event bus. Subscribe with chart.on(type, handler), which returns a disposable:

const subscription = chart.on('barclick', event => {
    // The handler receives an `Event`, not the payload — the payload is `event.data`.
    const { seriesId, xValue, yValue } = event.data;

    console.log(seriesId, xValue, yValue);
});

subscription.dispose();

An Event also carries type, timestamp, target (the bus it was emitted on) and stopPropagation(). Alongside its own interaction events, every chart emits destroyed (with no payload) when chart.destroy() runs — useful for tearing down anything bound to the chart.

Each chart's page lists the events it emits, with the payload type for each.

Lifecycle

Shared by every chart, regardless of type:

Method	Description
`update(options)`	Merges partial options over the current ones and re-renders (when `autoRender` is enabled)
`render()`	Renders explicitly; resolves once entry/update transitions have settled
`export()`	Exports the rendered chart from its context
`destroy()`	Tears the chart down and releases its scene, renderer and listeners

Shared Options ​

Padding ​

Animation ​

Title ​

Axis ​

X-Axis Options ​

Y-Axis Options ​

Format Types ​

Grid ​

Tooltip ​

Legend ​

Crosshair ​

Input Shorthand ​

Theme ​

Annotations ​

Panning & Zooming ​

Accessibility ​

Spacing ​

Events ​

Lifecycle ​

Shared Options

Padding

Animation

Title

Axis

X-Axis Options

Y-Axis Options

Format Types

Grid

Tooltip

Legend

Crosshair

Input Shorthand

Theme

Annotations

Panning & Zooming

Accessibility

Spacing

Events

Lifecycle