chartXY() has a real extension hook: chart.use(plugin) with typed install/onRender/onDispose callbacks, plus a components config for turning the built-in legend/cursor/markers/limit-lines/ detection-bars/annotations/restore-button on or off per chart. This mirrors docs/guides/components.md directly.
Every chartXY() chart is built from a small set of optional visual systems — legend, hover tooltip, value markers, limit lines, detection bars, annotations, and the "restore view" button. By default all of them are on, so a bare chartXY({ container }) looks and behaves exactly the way it always has.
You don't need any of this to get a working chart — see Getting started first if you haven't already. This guide is for when you want to add or remove specific pieces.
Say two developers both need a 2D chart, but want different things on it:
Both are one option, no subclassing, no extra packages:
import { chartXY } from "@rekhly/charts-2d";
// User A
const chartA = chartXY({
container: "#chart-a",
components: { legend: true, markers: true, limitLines: true },
});
chartA.markers.add({
id: "peak",
kind: "symbol",
shape: "triangle-down",
position: { mode: "absolute", x: 12, y: 98 },
label: "Peak",
line: "vertical",
draggable: true,
});
chartA.limitLines.add({ id: "max", orientation: "horizontal", value: 100, direction: "above" });
// User B
const chartB = chartXY({
container: "#chart-b",
components: { legend: true, cursor: false, markers: false, limitLines: false, detectionBars: false, annotations: false, restoreButton: false },
});
Typing out every flag for "just the legend" is tedious, so there's a shorthand: pass false to start from everything off, then opt back in — or use one of the built-in presets.
import { chartXY, CHART_PRESETS } from "@rekhly/charts-2d";
// Same as chartB above.
const chartB = chartXY({ container: "#chart-b", components: CHART_PRESETS.legendOnly });
components optionXYChartOptions.components accepts three shapes:
| Value | Meaning |
|---|---|
| *(omitted)* | Everything on — the default chart. |
false |
Everything off — a bare plot with just axes and series. |
true |
Same as omitting it: everything on. |
{ legend: true, cursor: false, ... } |
Only the listed flags are set; everything else stays at its default (on). |
The individual flags:
| Flag | Controls | Underlying object |
|---|---|---|
legend |
Series legend, top-left by default (see Positioning), click to toggle a series | chart.legend |
cursor |
Hover crosshair + tooltip | chart.cursor |
markers |
Symbol / cursor / display-line / range / delta markers (FacMarker parity) | chart.markers — see Markers |
limitLines |
Threshold lines with breach detection | chart.limitLines |
detectionBars |
Highlighted x-range bands | chart.detectionBars |
annotations |
Draggable hline/vline/rect/text annotations | chart.annotations |
restoreButton |
Circle-with-dot button shown once the view is zoomed/panned | — |
toolbar |
Bottom-center pill: Sweep Once / Sweep Continuously (toggles) / Zoom in / Zoom out | — (see Interactions) |
overview |
ZoomOverview minimap — cyan brush = main viewport after zoom | — (see Zoom Overview) |
Important: disabling a component only stops it from *rendering*. The object is still there and still works — chart.markers.add(...) never throws just because markers: false. This means you can build up chart state ahead of time and flip components on later (see Reconfiguring at runtime) without losing data.
CHART_PRESETS from @rekhly/charts-2d covers the common combinations so you don't have to spell out every flag:
import { CHART_PRESETS } from "@rekhly/charts-2d";
CHART_PRESETS.full // everything on (the default)
CHART_PRESETS.minimal // everything off
CHART_PRESETS.legendOnly // just the legend
CHART_PRESETS.cursorOnly // just the hover tooltip
CHART_PRESETS.dashboard // legend + cursor + restore button (no markers/annotations)
CHART_PRESETS.trading // legend + cursor + markers + limit lines + restore button
Presets are plain objects — spread one and override a flag or two:
chartXY({
container,
components: { ...CHART_PRESETS.trading, cursor: false },
});
setComponents merges with whatever is currently on, so you only pass the flags you want to change:
const chart = chartXY({ container, components: CHART_PRESETS.minimal });
// ...user clicks a "show tooltip" toggle in your UI...
chart.setComponents({ cursor: true });
// Inspect the current state (e.g. to sync a settings panel):
chart.getComponents(); // { legend: false, cursor: true, markers: false, ... }
Pointer/wheel gestures are controlled separately from components, via XYChartOptions's runtime twin setUserInteractions:
chart.setUserInteractions({ zoom: true, pan: true, rectangleZoom: true, restore: true });
// or: chart.setUserInteractions(false) to turn every gesture off at once
| Flag | Controls |
|---|---|
zoom |
Wheel zoom. Hold Alt to zoom Y only, Shift to zoom X only. |
pan |
Click-drag to pan. |
rectangleZoom |
Box zoom — Shift+drag, or click the ▭ toolbar button (top-right, next to restore) then drag once. The button auto-returns to pan mode after one drag. |
restore |
The circle-with-dot restore-view button (also gated by components.restoreButton). |
All four default to true. Panning and wheel-zooming are clamped to the series' data domain — you can't drag or zoom the view out past the edges of the data, only up to the small padding the chart already adds around a freshly-fitted view.
Gated by components.toolbar (on by default), the bottom-center pill gives every chart Sweep Once / Sweep Continuously / Zoom in / Zoom out for free. There is no separate Pause button — each sweep button is a toggle: click to start, click the same button again to abort mid-run.
> [!NOTE] > Zooming the chart (via the toolbar, scroll wheel, or box zoom) while a sweep is running does not pause the sweep. The chart will continue sweeping at the new zoom level. Manually panning the chart will pause the sweep, allowing you to inspect historical data.
chart.zoomIn();
chart.zoomOut();
// Axis-scroll sweep (fallback — see below):
chart.setSweepMode("sweep-once"); // one pass across the current window, then holds
chart.setSweepMode("sweep-multi"); // repeats that pass
chart.setSweepMode("continuous"); // back to the default trailing-window scroll
// Source-driven sweep — the chart pushes data itself:
chart.setSweepSource(
(frame) => series.appendSamples(nextBatch(frame)),
{ totalFrames: 200, intervalMs: 60 },
);
chart.runSweepOnce(); // == clicking Sweep Once while idle
chart.runSweepRepeat(); // == clicking Sweep Continuously while idle
chart.stopSweep(); // == clicking the running sweep's button again
chart.getSweepStatus(); // "idle" | "running" | "aborted"
chart.getActiveSweepAction(); // "sweep-once" | "sweep-multi" | undefined
chart.onSweepStatus((status) => { /* ... */ });
Value markers are frozen during Sweep Continuously (locked at their placed position) and remain draggable in both Once and Continuously — drag is the only way they move while Continuously runs. Use viewport-relative markers on scrolling ring buffers. Full details: Markers.
Without a registered setSweepSource, the toolbar falls back to setSweepMode's axis-scroll behavior, which only animates on a scrollable axis (axis.setScrollMode(...) / axis.setVisibleRange({ width })) as new data arrives — it repositions the visible window each time a series appends data, it does not run its own timer. For a static dataset, register a setSweepSource (the chart paces the ticks itself via the engine's frame loop) or turn the toolbar off (components: { toolbar: false }) and drive your own reveal animation — see Sweep controls for a ready-made "reveal this dataset over N frames" helper used across examples/**.
Attach a mountSweepStatusBar to show one or more charts' Idle / Running / Aborted state outside the chart itself — useful in a dashboard header.
Title, legend, toolbar, and the restore/box-zoom button pair are each independently positioned on a 3x3 grid — any combination of {top,middle,bottom} x {left,center,right} — instead of a fixed corner:
import { chartXY, type OverlayPosition } from "@rekhly/charts-2d";
const chart = chartXY({
container,
titlePosition: "bottom-right", // default: "top-center"
toolbarPosition: "bottom-left", // default: "bottom-center"
controlsPosition: "middle-right", // default: "top-right" (restore + box-zoom pair)
});
chart.setLegendOptions({ position: "bottom-right" }); // default: "top-left"
// All nine anchors, for building a position picker:
import { OVERLAY_POSITIONS } from "@rekhly/charts-2d";
// ["top-left", "top-center", "top-right", "middle-left", "middle-center",
// "middle-right", "bottom-left", "bottom-center", "bottom-right"]
Runtime setters mirror the construction options:
chart.setTitlePosition("bottom-right");
chart.setToolbarPosition("bottom-left");
chart.setControlsPosition("middle-right");
chart.setLegendOptions({ position: "bottom-right" });
controlsPosition moves the restore-view and box-zoom buttons together as a pair, laid out side-by-side at whichever anchor you pick — no manual offset math needed. If a title and a legend end up sharing the same corner, titlePosition's companion option, titleOffset (a signed pixel dy, also settable at runtime as setTitlePosition(position, dy)), lifts the title clear of the legend beneath it:
chartXY({ container, titlePosition: "bottom-right", titleOffset: -46 });
OverlayPosition (and the type name LegendPosition re-exported for backward compatibility) covers all 9 anchors; the four corner values used before this existed ("top-left", "top-right", "bottom-left", "bottom-right") still mean exactly what they did.
The components flags cover the chart's built-in visual systems. For anything beyond that — a custom watermark, a stats overlay, wiring the chart into your own analytics, syncing state to a store — attach a ChartPlugin instead of forking the library:
import type { ChartPlugin } from "@rekhly/charts-2d";
const watermark: ChartPlugin = {
name: "watermark",
install(chart) {
const el = document.createElement("div");
el.textContent = "Acme Corp";
el.style.cssText = "position:absolute;right:8px;bottom:8px;opacity:0.4;font:11px sans-serif;pointer-events:none;";
chart.overlay.appendChild(el); // chart.overlay is the same DOM layer legend/markers/annotations paint into
},
onRender(chart) {
// called after every chart.render() — e.g. reposition something, log a metric
},
onDispose(chart) {
// clean up anything you created in install()
},
};
chart.use(watermark);
install runs once, immediately. onRender runs after every render (including the ones triggered internally by zoom/pan/resize). onDispose runs once, before the chart tears down its engine and DOM. A plugin can be as small as a single hook — all three are optional.
The Python SDK builds the same chart configuration (see ChartXY.serialize()) that the runtime on the JavaScript side renders. Component configuration is not yet exposed as a typed Python option — track KNOWN_GAPS.md for that, or set it up on the JavaScript/React side that hosts the runtime.
drag during Sweep Once / Continuously.
live and static datasets.
@rekhly/charts-2d README — packageoverview and install.
Got any questions? I'm happy to help with products, licensing, and examples.