Bar replay
Enable and customize the bar replay UI, add custom tick or sub-bar resolution controls, synchronize multi-chart grids, and control replay programmatically.
Bar replay rewinds a chart or multi-chart workspace to a historical bar and steps forward through subsequent market data for practice and analysis. Vela's open-source core provides the underlying replay engine, while Vela Pro adds the interactive user interface, including a topbar Replay button, an on-chart start-bar picker, and a floating or dockable playback bar.
enableVelaPro() enables the replay interface by default. Pass replay options to customize initial playback behavior or attach custom dropdown controls to the bar:
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro, replayResolutionControl } from '@luxalgo/vela-pro';
enableVelaPro({
replay: {
controls: [replayResolutionControl()], // synthesize intrabar updates from finer timeframes
defaultSpeed: 2,
},
});
const workspace = new VelaWorkspace('#chart', {
layout: false,
symbol: 'BTCUSDT',
timeframe: '60',
live: true,
providers: { binance: () => new BinanceProvider() },
});Pass enableVelaPro({ replay: false }) to disable the replay UI while keeping the core programmatic replay API available, or call enableReplay(options) to install the replay UI without other Vela Pro features.
Starting a replay
Clicking Replay in the topbar (to the right of Indicators) enters start-bar selection mode:
- The crosshair switches to a vertical cutoff line and shades bars to the right so the user can preview which bars will be hidden.
- Clicking a bar rewinds the workspace to that bar in a paused state and opens the replay control bar. Pressing
Esccancels selection mode. - Seeking to a date earlier than the loaded bar window displays a progress indicator counting historical bars as they stream in (
Esccancels the fetch). Clicking Replay again while a session is active ends replay.
All active indicators recalculate over the rewound history and then update incrementally as each bar is revealed, matching live bar progression. Script alerts remain muted during replay, and live streaming resumes automatically when replay exits.
Control bar
| Control | Behavior |
|---|---|
| Grip | Drags the floating control bar anywhere inside the workspace |
| Start bar | Re-enters bar-pick mode to jump backward or forward to a new cutoff bar |
| Play, Pause | Starts or pauses timed playback |
| Next update | Advances manually by one bar (or one intrabar update during tick replay) |
| Replay speed | Selects 0.1x, 0.25x, 0.5x, 1x, 2x, 3x, 5x, or 10x (1x advances one update per second) |
| Custom controls | Renders any dropdowns supplied in replay.controls, in array order |
| Date readout | Displays the timestamp of the newest visible bar and opens a date picker calendar to seek by date |
| Bars left | Displays remaining bar count and opens a scrubber slider across loaded history |
| Pin to bottom, Unpin | Docks the bar as a full-width strip above the bottom bar, or detaches it back to floating mode |
| Exit replay | Ends replay and restores full history and live market updates |
While replay is active, Space toggles play/pause and Shift + ArrowRight steps forward one update. Both the floating bar position and its pinned state persist in browser storage across reloads.
On narrow mobile viewports, Replay moves into the overflow (three-dots) menu and the playback bar always docks above the bottom bar. Start selection places the cutoff line immediately at the center of the chart; dragging and lifting a finger starts replay at that bar, and a bottom strip offers Start here and Cancel actions. See Responsive layout for mobile details.
Configuration options
| Option | Default | Description |
|---|---|---|
controls | [] | Additional ReplayBarControl dropdowns rendered after the speed selector |
defaultSpeed | 1 | Initial playback speed multiplier (must match one of the bar's speed presets) |
pickShade | Chart background at 0.6 opacity | Veil drawn over bars to the right of the pick cursor as { color, opacity }, or false to disable shading |
keys | true | Enables Space (play/pause) and Shift + ArrowRight (step) keyboard shortcuts |
Multi-chart grids and symbol changes
Workspace replay runs every chart cell on a single shared clock. When a user picks a start bar in any cell, every other cell rewinds to the same timestamp, retaining only bars that had closed by that moment. During playback, the cell with the finest timeframe sets the step cadence, and cells on coarser timeframes reveal their next bar once its closing timestamp is reached.
Active replay sessions stay synchronized across mid-session changes:
- Switching a cell's timeframe keeps the cell anchored at the current replay timestamp on the newly loaded timeframe series and continues playback.
- Switching a cell's symbol rejoins the shared replay timestamp as soon as historical bars for the new symbol finish loading.
- Expanding the grid layout synchronizes newly created cells to the active replay timestamp.
Replay terminates across all cells simultaneously when the user clicks Exit replay or when a cell reveals its final bar. For full multi-cell clock semantics, see Bar replay across the grid in the core documentation.
Custom bar controls and tick replay
Each ReplayBarControl mounts a custom dropdown on the replay bar with an id, options, and an onChange handler receiving the selected value and active chart. The example below connects a custom historical trade endpoint to the core's tick replay API so candles form trade by trade instead of whole bars:
import type { ReplayTick, ReplayTickSource, Vela } from '@luxalgo/vela';
import { enableVelaPro, type ReplayBarControl } from '@luxalgo/vela-pro';
// Fetch historical trades inside a single bar window, ordered oldest first.
const tradesOf = (chart: Vela): ReplayTickSource => async (bar, { end, signal }) => {
const query = `symbol=${chart.market.symbol}&from=${bar.time}&to=${end}`;
const res = await fetch(`/api/trades?${query}`, { signal });
return (await res.json()) as ReplayTick[];
};
const source: ReplayBarControl = {
id: 'source',
title: 'Replay from',
tooltip: 'Granularity used to build each replayed candle',
options: [
{ value: 'bars', label: 'Whole bars', selected: 'Bars' },
{ value: 'trades', label: 'Trades' },
],
value: 'bars',
onChange: (value, { chart }) => {
chart.replay.setTicks(value === 'trades' ? tradesOf(chart) : null);
},
};
enableVelaPro({ replay: { controls: [source] } });Each ReplayTick specifies price along with optional high, low, open, and volume fields. onChange runs whenever the user picks an option and re-runs with the current selection each time the replay bar binds to a new active chart, so keep the callback idempotent. options can also be a function (chart) => [...], which is re-evaluated whenever replay starts.
replayResolutionControl() is a built-in ReplayBarControl that populates candidate timeframes finer than (and evenly dividing) the chart's timeframe alongside Auto (whole bars), synthesizing intrabar updates from lower-timeframe candles fetched from the chart's provider. For example, at 1x, a 15-minute candle built from 1-minute bars unfolds over 15 seconds. Pass { timeframes } to customize the candidate intervals (defaults to ['1', '5', '15', '30', '60', '240', 'D']).
Intrabar tick and sub-bar resolution replay require a single-chart layout. In multi-chart grids, replay always steps by whole bars regardless of control selection.
Programmatic control
Vela Pro's replay bar drives workspace.replay and subscribes to its events, so starting a replay from code displays the same control bar in the UI, and user-initiated replay actions fire your event listeners:
import type { VelaWorkspace } from '@luxalgo/vela/workspace';
declare const workspace: VelaWorkspace;
await workspace.chart.ready();
const { replay } = workspace;
const bounds = replay.bounds; // earliest and latest timestamps available for replay
if (bounds) {
await replay.start({ from: (bounds.first + bounds.last) / 2 }); // rewinds in paused state
replay.play(500); // advance one update every 500 ms
}
replay.on('replay:step', ({ cursorTime, remaining }) => {
console.log(new Date(cursorTime).toISOString(), `${remaining} bars left`);
});
replay.on('replay:end', ({ reason }) => console.log(`replay ended: ${reason}`));| Member | Description |
|---|---|
start({ from, cell? }) | Starts replay at from (epoch ms), or seeks when already active. cell specifies which cell's series resolves the timestamp (defaults to the active cell). Resolves once all cells render their rewound history |
step(), stepUpdate() | Advances by one full bar (step) or one intrabar tick update (stepUpdate) |
play(intervalMs?), pause() | Starts or pauses timed playback; calling play() again while playing updates the step interval |
stop() | Exits replay, restores full bar history, and resumes live updates |
state | Read-only snapshot with active, playing, cursorTime, remaining, nextTime, and intervalMs |
bounds | { first, last } timestamps in epoch ms, or null before bars have loaded |
on(event, handler) | Subscribes to replay:start, replay:step, replay:tick, replay:play, replay:pause, and replay:end |
Each individual chart also exposes chart.replay (with the same playback methods plus setTicks) and emits replay:* events through chart.on. Calling chart.replay directly replays only that chart instance, so prefer workspace.replay in workspaces. For complete method signatures, see chart.replay and tick replay in the core API reference.
Related
Custom drawing tools
Customize built-in drawing tools with presets and toolbar groups, or contribute new interactive drawing tool classes to Vela's open-source core.
Events and subscriptions
Access active charts and cells, update symbols, timeframes, and layouts programmatically, and subscribe to workspace, chart, and Vela Pro events.