Candlestick chart

Sand pours into each candle's body and resolves into a solid open-close block, while the high-low wicks are stroked solid throughout. Every candle is colored rising or falling by a configurable difference rule, and a dashed live-price line tracks the latest actual.

Constructor

new CandlestickChart(host: HTMLElement, config: CandlestickChartConfig)

Mounts a canvas into host and boots the best backend (WebGPU → Canvas2D). Only data is required.

Data — OhlcDataSet

interface Candle {
  x: Scalar;          // period start: a Date, a number, or a category label
  open: number;
  high: number;
  low: number;
  close: number;
  actual?: number;    // live / last traded price — drives the live-price line
}

interface CandleSeries { key?: Scalar; candles: Candle[]; }
interface OhlcDataSet  { series: CandleSeries[]; xType?: FieldType; }

actual is orthogonal to close: on a streaming feed the newest candle's close is still provisional while actual is the price right now. It never affects a candle's own geometry — only the live-price line, the price-axis domain (so the line always stays on screen) and the hover readout.

Config — top level

candles

One block for everything about a candle: what color it is, what its body spans, and the solid layer that resolves as the sand fades out. Mirrors the bar chart's bars.

Color rules — candles.direction

Which difference decides a candle's color. All the rules that look backwards fall back to 'openClose' for the first candle of a series, since nothing precedes it.

actual — the live-price line

A horizontal rule across the plot at the latest Candle.actual in the drawn series (the last candle that carries one), with a value marker on the price axis. Off by default: without an actual block the values still travel through hover and events, but nothing is drawn.

The live price is folded into the price-axis domain, so a line that has run past every candle's range still stays on screen.

spacing

animation

Same as the bar chart, with the three-way twists named for candles:

Overriding mouse events — interaction.mouse

Every built-in mouse reaction can be cancelled or replaced, through the same hook contract the wind rose uses (core/interaction/mouse.ts). Each hook receives a context —

{
  meta: CandleMeta | null;   // the mark under the pointer
  native: PointerEvent;      // modifier keys, coordinates, preventDefault
  px: { x: number; y: number };   // CSS px, relative to the chart element
  defaultAction(): void;    // run the built-in behavior — idempotent
}

Return false to suppress the built-in behavior; return anything else — including nothing — to let it run after the hook, unless the hook already called defaultAction() itself.

Shared blocks

axes, legend, title, currentValue, interaction.hover, interaction.dim and fps are the same config the bar chart documents — see bar chart → axes / legend / currentValue / fps. Pan & zoom is the shared panZoom block.

Methods

It also implements the shared PanZoomable interface: getView(), setView(v), panBy(), panTo(), zoomBy(), zoomTo(), resetView(), isPanZoomEnabled().

Events

hover carries { candle: CandleMeta | null } and click carries { candle, event }. Hit-testing is by column: anywhere in a candle's slot selects it, the way a trading chart's crosshair behaves, rather than demanding a hit on the thin body.

// CandleMeta — metadata for one drawn candle
{
  candleId: number;          // index within the drawn series; also the grain barId
  indexInSeries: number;
  seriesIndex: number;
  seriesKey: Scalar | undefined;
  xValue: Scalar;
  open: number; high: number; low: number; close: number;
  actual: number | undefined;
  rising: boolean;            // what the direction rule decided
  x0: number; x1: number; cx: number;      // body edges + center, layout space [0,1]
  bodyLow: number; bodyHigh: number;   // body extent, layout space
  wickLow: number; wickHigh: number;   // full price range, layout space
  color: RGBA;
}

seriesChange carries { index, key } (the instrument the slider moved to) and seriesFocus carries { index: number | null } (the isolated direction group).

Examples

Solid candles with axes and a live price

new CandlestickChart(el, {
  data: {
    series: [{
      key: 'ACME',
      candles: [
        { x: new Date('2026-01-05'), open: 120, high: 124, low: 119, close: 123 },
        { x: new Date('2026-01-06'), open: 123, high: 125, low: 121, close: 121.5, actual: 122.2 },
      ],
    }],
  },
  candles: {
    fill: { opacity: 0.9 },
    border: { width: 1 },
    reveal: { duration: 500, grainsTo: 0.12 },
  },
  actual: { show: true },
  axes: { x: { show: true, ticks: 6 }, y: { show: true, gridLines: true } },
});

Sand only — no solid bodies

// No fill and no border: the bodies stay sand forever, only the wicks are solid.
new CandlestickChart(el, {
  data,
  grainDensity: 2.2,
  candles: { width: 0.8, reveal: { grainsTo: 1 } },
});

Coloring by the previous close, not the open

new CandlestickChart(el, {
  data,
  candles: { direction: 'closeClose', rising: '#2eb872', falling: '#e0555c' },
});

A custom color rule

// Rising while the close holds above a level your own code computes.
new CandlestickChart(el, {
  data,
  candles: {
    direction: (candle, previous, index) => candle.close >= movingAverage(index),
  },
});

Range bars instead of candles

new CandlestickChart(el, {
  data,
  candles: { body: 'lowHigh', width: 0.5, fill: { opacity: 0.7 } },
});

Streaming: tick the live price, roll the window

const chart = new CandlestickChart(el, {
  data,
  candles: { fill: {}, border: {} },
  actual: { show: true },
  animation: { enter: 'continue' },   // new bars appear settled, no pour
});

// Every tick: patch only what moved on the bar still being filled.
feed.on('price', ({ x, price }) => {
  chart.update([{ x, close: price, actual: price }]);
});

// Every period: append the new bar and drop the oldest — surviving candles slide.
feed.on('bar', (bar) => {
  chart.add(bar);
  chart.remove(0);
});

Switching instruments

const chart = new CandlestickChart(el, {
  data: { series: [{ key: 'ACME', candles: acme }, { key: 'GLOBEX', candles: globex }] },
  slider: { show: true, position: 'bottom' },
  axes: { x: { show: true, label: 'instrument' } },
});

chart.on('seriesChange', ({ index, key }) => console.log('now showing', key));
chart.setSeriesIndex(1);   // same animation as dragging the slider

Isolating rising or falling candles

new CandlestickChart(el, {
  data,
  candles: { fill: {} },
  legend: { show: true, interactive: true },   // entries: Rising / Falling
  interaction: { dim: { opacity: 0.15 } },
});

chart.focusSeries(0);   // show only rising candles at full opacity

Driving your own tooltip (overriding the mouse events)

new CandlestickChart(el, {
  data,
  interaction: {
    mouse: {
      onCandleHover({ meta, px }) {
        myTooltip(meta, px);
        return false;   // suppress the built-in readout (the hover event still fires)
      },
      onCandleClick({ meta }) {
        selectPeriod(meta?.xValue);
      },
      onSliderSeek({ meta: index, defaultAction }) {
        if (isLoaded(index)) defaultAction();   // switch now…
        else load(index).then(defaultAction);   // …or once the data arrives
        return false;
      },
    },
  },
});