Data and updates

Candle shapeCopy Anchor Link

import type { Candle } from '@bloxwap/chart';

const candle: Candle = {
  time: 1700000000, // UNIX seconds
  open: 100,
  high: 105,
  low: 98,
  close: 103,
  volume: 2400, // optional
};

Provide finite numeric prices and valid OHLC bounds: low should not exceed the open/close, and high should not be below them. The library expects usable market data rather than performing feed validation.

Replace historyCopy Anchor Link

chart.setData(candles) replaces the history, sorts timestamps when needed, invalidates indicator calculations, and redraws. Supply one candle per timestamp. The array is copied, but treat candle objects as immutable after handing them to the chart.

Time on the horizontal axis is indexed by bars by default. Missing timestamps do not reserve empty columns; aggregate your feed into your desired interval before passing it in. To show gaps such as weekends as empty space, turn on the time-continuous axis.

Append or update a candleCopy Anchor Link

chart.appendData({ time: 1700003600, open: 103, high: 108, low: 102, close: 107 });

// Same timestamp replaces that bar as its price changes.
chart.appendData({ time: 1700003600, open: 103, high: 110, low: 102, close: 109 });

appendData appends a new latest timestamp, replaces an existing timestamp, or inserts an earlier candle in timestamp order. A candle older than the first one is added like prependData, so index-based drawings stay on their bars. It does not open a WebSocket or subscribe to an exchange. The playground (apps/playground/index.html) shows a complete example: it seeds the chart from Hyperliquid's candleSnapshot REST endpoint and streams live BTC perpetual candles from the candle WebSocket subscription into appendData.

Your application owns symbol changes, interval aggregation, retries, feed validation, and subscription cleanup. The paging datafeed handles most of that for you: it loads history for a symbol and interval, pages older bars in as the user scrolls, and folds live price ticks into bars.

Add older historyCopy Anchor Link

const added = chart.prependData(olderCandles); // returns how many candles were added

prependData puts older history in front of the loaded data, as a datafeed does when the user scrolls back:

• Rows at or after the current first candle are ignored, as are rows with a non-finite time or price. The rest are deduped by time (the last row wins) and sorted.
• The view stays on the same candles at the same pixels, including on a continuous time axis.
• Drawings tied to bars move with their bars, including a drawing still being placed and the toolbar's undo history. Screen-anchored drawings stay put.
• Indicators recompute, and subscribeDataLoad listeners receive { reason: 'prepend', added }.

DataStore, exported from the root entry, has the lower-level prepend(older), which expects rows that are already sorted, unique, and older than the first candle.

Group updates into one redrawCopy Anchor Link

chart.batch(() => {
  chart.appendData(nextCandle);
  chart.updateConfig({ statusLine: { visible: true, symbol: 'BTC / USD' } });
});

Batching is synchronous and supports nesting. Avoid passing an async callback if you expect updates after an await to remain in the same batch.

Reading stateCopy Anchor Link

chart.getData() returns the loaded candles, oldest first, exactly as the chart holds them: after setData, appendData, prependData, and every datafeed load. Use it when the chart is fed by a datafeed and you need the bars back, for example to place markers or to read the previous close:

const bars = chart.getData();
const previousClose = bars.at(-2)?.close;

It returns the chart's own array, not a copy. Don't mutate it, and call it again after a data change instead of keeping it: the next load may replace it. chart.dataLength gives the current number of candles. getConfig().data describes configured input; it is not a live snapshot after setData, appendData, or a datafeed load.

To react to data changes, subscribe to them. Each event reports the reason ('set', 'append', 'update', or 'prepend'), the candles added, the new length, and the first and last times:

const off = chart.subscribeDataLoad(({ reason, added, length }) => console.log(reason, added, length));

See chart events for the visible range, crosshair, and layout events too.