# Bar replay (/vela-pro/charts/replay)



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:

```ts
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 [#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 [#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](/vela-pro/customization/mobile/responsive) for mobile details.

## Configuration options [#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 [#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](/vela/user/workspace#bar-replay-across-the-grid) in the core documentation.

## Custom bar controls and tick replay [#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:

```ts
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']`).

<Note>
  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.
</Note>

## Programmatic control [#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:

```ts
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`](/vela/user/api-reference#chartreplay--the-bar-replay-control-surface) and [tick replay](/vela/user/api-reference#tick-replay) in the core API reference.

## Related [#related]

* [Events and subscriptions](/vela-pro/charts/events)
* [Interface layout](/vela-pro/customization/interface)
* [Keyboard shortcuts](/vela-pro/customization/shortcuts)
