API Reference modified by Zulfikar

Zulfikar — Mon, 20 Jul 2026 01:18:37 -0000

API Reference

`chart(container, config)` / `new Chart(container, config)`

Creates and immediately renders a chart. container is an element or a CSS selector string.
Returns a Chart instance.

Config

Option	Type	Default	Notes
`data`	`Array<object>`	—	Row data. Use with `x` / `y` / `series`.
`x`	`string`	`'label'` / `'x'`	Accessor key for the x value.
`y`	`string`	`'value'` / `'y'`	Accessor key for a single-series y value.
`series`	`Array<{key,label?,color?,y?}>`	—	Multiple series from the same rows.
`xs`, `ys`	`Float64Array`	—	Typed-array fast path. Bypasses row parsing.
`count`	`number`	`ys.length`	Number of valid entries in `xs`/`ys`.
`size`	`string`	—	Accessor for bubble radius (with `mark:'bubble'`).
`mark`	`string \\| object`	`'line'`	Chart type. Object form carries mark options.
`renderer`	`'canvas' \\| 'svg'`	`'canvas'`	Drawing surface.
`theme`	`'light' \\| 'dark' \\| object`	`'light'`	Token set; objects deep-merge onto a base.
`title`	`string`	—	Drawn top-left.
`xLabel`, `yLabel`	`string`	—	Axis titles.
`width`, `height`	`number`	container size	Pixel size override.
`margins`	`{top,right,bottom,left}`	auto	Plot insets.
`animate`	`boolean`	`true`	Auto-disabled above 50k points.
`grid`	`boolean`	`true`	Background gridlines.
`legend`	`boolean`	auto	Forced on/off; auto for multi-series, arc, radar.
`tooltip`	`boolean`	`true`	Hover tooltip + quadtree hit-testing.
`zoom`	`boolean`	`false`	Drag to pan, wheel to zoom (x-domain).
`crosshair`	`boolean`	`false`	Vertical guide line following the pointer; emits `crosshair` events for multi-panel sync.
`xPad`	`number`	—	Expand the numeric x-domain by this many x-units per side (e.g. `0.5` so edge bars/candles aren't clipped).
`axes`	`boolean`	`true`	Set `false` to hide axes entirely (e.g. for sparklines).
`maxPoints`	`number`	—	Enables ring-buffer sliding window for live data.
`a11y`	`{label,description}`	—	Overrides the generated ARIA text.

Mark options (object form)

mark: { type: 'gauge', value: 72, min: 0, max: 100 }
mark: { type: 'donut', innerRatio: 0.6, centerLabel: 'Total' }
mark: { type: 'line', mode: 'spline', decimate: false }
mark: { type: 'histogram', value: 'amount', bins: 20 }
mark: { type: 'boxplot', groups: [{ label, values: [] }] }
mark: { type: 'sankey', nodes: [{ id, name }], links: [{ source, target, value }] }

String shorthands map to {type, mode}: column/bar, hbar, stacked-bar, grouped-bar,
waterfall, line, spline, step, area, stacked-area, streamgraph, scatter,
bubble, pie, donut, gauge, radial-bar.

Instance methods

`render(animate?)`

Draws the chart. Pass false to skip the entry animation.

`update(data | { xs, ys, count })`

Replaces the dataset and redraws (re-animating). Accepts row arrays or typed arrays.

`appendData(point | point[])`

Appends one or more {x, y} points for live charts. Multiple calls within a frame are batched
into a single redraw via the frame scheduler. With maxPoints set, data flows through a ring
buffer so memory stays constant.

`stream(source, map?)`

Connects a streaming source and appends as data arrives. Supports:

an async iterator / async generator,
an EventSource (map receives the parsed data),
a WebSocket (map receives the parsed message).

map(raw) => {x, y} adapts payloads. Returns the chart; call stopStream() to disconnect.

`setTheme('light' | 'dark' | object)`

Swaps theme tokens and redraws without animation. Object themes deep-merge onto light (or dark if
name: 'dark').

`resize()`

Re-measures the container and redraws. Also invoked automatically by a ResizeObserver.

`setCrosshair(x)`

Draws (or clears, with null) a vertical crosshair at a domain-x value without emitting an
event — use it to mirror one chart's crosshair onto others for synchronized multi-panel views
(see the trading-terminal template).

`toPNG()` → `string`

Returns a PNG data URL. SVG-rendered charts are rasterized through a temporary canvas.

`toSVG()` → `string`

Returns serialized <svg> markup, regardless of the active renderer.

`on(type, fn)` → `off`

Subscribes to 'hover', 'select' (click), 'append' (live), or 'crosshair' (pointer x over a
cartesian plot; payload {x, px} or null on leave). Returns an unsubscribe function.

`destroy()`

Removes listeners, the ResizeObserver, the stream connection, and DOM nodes.

Custom marks

import { Chart, registerMark } from 'lombok-charts';
import { Mark } from 'lombok-charts'; // base class via deep import if needed

class MyMark extends Mark {
  coordinate() { return 'cartesian'; }      // or 'none' for self-laid-out marks
  domains(series, opts, rawData) { return { x: {…}, y: {…} }; }
  draw(ctx) { /* ctx.r, ctx.sx, ctx.sy, ctx.area, ctx.series, ctx.hits, ctx.t */ }
  legendItems(series, ctx) { return null; } // or [{label, color}]
}
registerMark('mymark', MyMark);
chart('#app', { data, mark: 'mymark' });

See architecture.md for the draw-context contract.

Recent changes to API Reference

API Reference modified by Zulfikar

API Reference

chart(container, config) / new Chart(container, config)

Config

Mark options (object form)

Instance methods

render(animate?)

update(data | { xs, ys, count })

appendData(point | point[])

stream(source, map?)

setTheme('light' | 'dark' | object)

resize()

setCrosshair(x)

toPNG() → string

toSVG() → string

on(type, fn) → off

destroy()