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

Events and subscriptions

Access active charts and cells, update symbols, timeframes, and layouts programmatically, and subscribe to workspace, chart, and Vela Pro events.

View as Markdown

Host applications control a workspace through cell and workspace methods and react to user or market updates through typed event subscriptions. The example below keeps an external HTML <select> element synchronized in both directions with the active chart's symbol:

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
import { onActiveSymbol } from '@luxalgo/vela-pro/plugin';

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
});

const select = document.querySelector<HTMLSelectElement>('#symbol')!;

// Update the active chart when the external selector changes.
select.addEventListener('change', () => workspace.active.setSymbol(select.value));

// Update the external selector on symbol search picks, watchlist clicks, or state restores.
const stop = onActiveSymbol(workspace.context(), (symbol) => {
    if (!symbol) return;
    const ticker = workspace.chart.data.resolve(symbol)?.ticker ?? symbol;
    if (![...select.options].some((option) => option.value === ticker)) select.add(new Option(ticker));
    select.value = ticker;
});

onActiveSymbol is imported from @luxalgo/vela-pro/plugin, the plugin SDK entry used by Vela Pro modules. It invokes your callback immediately with the initial symbol, again whenever the active chart's symbol changes, and whenever focus moves to another chart cell.

Because symbol identifiers may carry a provider prefix (such as 'binance:BTCUSDT'), workspace.chart.data.resolve(symbol) extracts the bare ticker. Setting select.value in JavaScript dispatches no DOM change event, preventing feedback loops. Call stop() when tearing down the page.

Accessing charts and cells

A workspace contains either a single chart or a multi-chart grid, and shared workspace controls target whichever cell is currently active. Each chart slot in the workspace is represented by a cell handle:

ExpressionReturn value
workspace.chartActive Vela chart instance from Vela's open-source core (on, setMarket, renderer, drawings, replay)
workspace.activeActive cell handle (id, symbol, timeframe, priceStyle, and cell setters)
workspace.cell('eth')Cell handle matching the given ID, or undefined if not present
workspace.cells()Array of all cell handles currently mounted, in grid order
workspace.context()WidgetContext object passed to contributed actions and panels (symbol, togglePanel, openSymbolSearch, panels)

Read workspace.chart dynamically when you need it rather than caching the reference in a variable, because clicking another grid cell, switching layouts, or applying a saved state document can change or replace the underlying chart object.

Programmatic control

TargetMethod call
Symbolworkspace.active.setSymbol('ETHUSDT')
Timeframeworkspace.active.setTimeframe('15')
Chart typeworkspace.active.setPriceStyle('footprint')
Grid layoutworkspace.setLayout('2h')
Active cellworkspace.setActiveCell('eth')
Maximize or restore cellworkspace.maximizeCell('eth') (null to restore the grid)
Visible time rangeworkspace.chart.setVisibleRangePreset('1M') or setVisibleRange({ from, to })
Themeworkspace.setTheme('light')
Time zoneworkspace.setTimezone('America/New_York')
Side panelworkspace.context().togglePanel('vela-pro.watchlist', true)
Full workspace stateworkspace.applyState(state)

Unprefixed symbols route to the first registered provider that supports them, while prefixed strings ('binance:ETHUSDT') target a named provider explicitly. Cell setters update the chart in place, recomputing active indicators while preserving chart settings and event listeners. Because Vela Pro scopes drawings per symbol, switching symbols automatically swaps the displayed drawings (see Drawing persistence).

Built-in layout IDs are '1', '2h', '2v', '4', and '8', and layoutForGrid(rows, columns) from @luxalgo/vela/workspace builds custom grids up to 4×4 (setLayout is ignored when layout: false). Panel IDs are listed in Workspace layout, and state serialization is covered in Layouts and chart state.

Setter methods return immediately before network requests finish. Listen to market:changed or await workspace.chart.ready() after construction when you need to run code after bars have rendered.

Workspace events

workspace.on(event, handler) returns an unsubscribe function. A single workspace listener covers every cell in the grid, including cells created later by layout changes:

EventPayloadTrigger
cell:active{ id, prev }Focus moved to a different chart cell
cell:created, cell:destroyed{ id }A layout change or state restore mounted or removed a cell
layout:changed{ layout }The workspace switched grid layouts or rebuilt from saved state
cell:priceStyle{ id, from, to }A cell is switching chart types, emitted before repaint
cell:maximized{ id }A cell maximized over the grid, or returned to grid view (id is null)
script:runRun result plus cellAn indicator or strategy finished executing in any cell
state:changedNoneWorkspace state changed (debounced by approximately 500 ms)
locale:changed{ locale, direction }setLocale() updated the active language or text direction

Subscribe to state:changed to persist state documents to a backend (see Layouts and chart state), and use script:run to inspect indicator outputs or strategy metrics (see Backtest results).

Chart events

chart.on(event, handler) subscribes to events on an individual Vela chart instance:

EventPayloadTrigger
market:changed{ symbol, timeframe, prev }Symbol or timeframe changed and initial bars finished painting (prev holds the prior pair)
load:start{ symbol, timeframe, firstLoad }Initial series fetch started on an empty chart
load:end{ symbol, timeframe, bars }Initial series load painted (bars is 0 when no data was returned)
data:unresolved{ symbol, providers }No registered provider matched the requested symbol
data:unavailable{ symbol, timeframe, reason, finest, default }The provider permanently rejected the series (for example, an unsupported timeframe)
barBarLive tick update, newly closed bar, or bar revealed during replay
viewport:changed{ from, to }Visible time range panned or zoomed
indicator:added, indicator:removed{ id }An indicator was added to or removed from the chart
indicator:error{ id, error }A script indicator encountered a compile or runtime error
drawing:created, drawing:edited, drawing:removed{ id }A drawing was created, modified, or deleted
alertScript alert payloadA running script triggered an alert condition
theme:changedResolved theme objectChart theme updated via API or Chart settings
replay:start, replay:step, replay:endSee Bar replayReplay started, stepped forward, or ended

For the complete catalog of core chart events and payload types, see Chart-level events in the core API reference.

Because chart.on() attaches to a single chart instance, listeners tracking whichever chart is active should rebind on cell:active and layout:changed:

import type { VelaWorkspace } from '@luxalgo/vela/workspace';

declare const workspace: VelaWorkspace;
declare function showLastPrice(price: number): void;

let off = (): void => {};
const follow = (): void => {
    off();
    off = workspace.chart.on('bar', (bar) => showLastPrice(bar.close));
};

follow();
workspace.on('cell:active', follow);
workspace.on('layout:changed', follow);

Alternatively, onActiveChart(workspace.context(), callback) from @luxalgo/vela-pro/plugin tracks active-chart changes automatically on a 400 ms polling interval. Prefer the explicit cell:active and layout:changed subscriptions above when you need synchronous rebinding.

Vela Pro feature handles and events

Vela Pro features expose dedicated controller handles for programmatic inspection and event subscriptions. codeEditor() and bottomDock() return null when the corresponding feature is disabled:

import type { VelaWorkspace } from '@luxalgo/vela/workspace';
import { bottomDock, codeEditor } from '@luxalgo/vela-pro';

declare const workspace: VelaWorkspace;

const editor = codeEditor(workspace);
editor?.onDidEndRun(({ mode, ok, error }) => {
    if (!ok) console.warn(`${mode} failed: ${error?.message}`);
});

workspace.replay.on('replay:start', () => console.log('replay started'));
workspace.replay.on('replay:end', ({ reason }) => console.log(`replay ended: ${reason}`));

const dock = bottomDock(workspace.root);
dock?.onChange(() => console.log(dock.isOpen ? `bottom panel: ${dock.active}` : 'bottom dock closed'));

const panels = workspace.context().panels;
panels.onDidChange(() => console.log(`side panel: ${panels.openId() ?? 'none'}`));
FeatureAccessorEvents and state
Code editorcodeEditor(workspace)onDidStartRun ({ mode }), onDidEndRun ({ mode, ok, error }), onDidChangeTarget, onDidChangeCode, where mode is 'run' or 'update'. See Pine code editor
Replayworkspace.replayreplay:* events across the shared workspace clock. See Bar replay
Bottom dockbottomDock(workspace.root)onChange, plus isOpen and active properties
Side panelsworkspace.context().panelsonDidChange, plus openId() (provided by the core)
ModulestradingController(), alertsController(), and sibling controllersOrder lifecycle, fills, triggered alerts, and watchlist updates. See Modules and widgets

Menus, dialogs, and panels also dispatch DOM custom events on the workspace root element so host code can observe UI state without MutationObservers. See Following menus and panels in the core documentation.

On this page