Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

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.

View as Markdown

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:

  1. The crosshair switches to a vertical cutoff line and shades bars to the right so the user can preview which bars will be hidden.
  2. Clicking a bar rewinds the workspace to that bar in a paused state and opens the replay control bar. Pressing Esc cancels selection mode.
  3. Seeking to a date earlier than the loaded bar window displays a progress indicator counting historical bars as they stream in (Esc cancels 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

ControlBehavior
GripDrags the floating control bar anywhere inside the workspace
Start barRe-enters bar-pick mode to jump backward or forward to a new cutoff bar
Play, PauseStarts or pauses timed playback
Next updateAdvances manually by one bar (or one intrabar update during tick replay)
Replay speedSelects 0.1x, 0.25x, 0.5x, 1x, 2x, 3x, 5x, or 10x (1x advances one update per second)
Custom controlsRenders any dropdowns supplied in replay.controls, in array order
Date readoutDisplays the timestamp of the newest visible bar and opens a date picker calendar to seek by date
Bars leftDisplays remaining bar count and opens a scrubber slider across loaded history
Pin to bottom, UnpinDocks the bar as a full-width strip above the bottom bar, or detaches it back to floating mode
Exit replayEnds 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

OptionDefaultDescription
controls[]Additional ReplayBarControl dropdowns rendered after the speed selector
defaultSpeed1Initial playback speed multiplier (must match one of the bar's speed presets)
pickShadeChart background at 0.6 opacityVeil drawn over bars to the right of the pick cursor as { color, opacity }, or false to disable shading
keystrueEnables 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}`));
MemberDescription
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
stateRead-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.

On this page