Watchlist
Configure the Watchlist module, manage symbol lists programmatically, persist watchlists to your backend, and connect a custom quote feed.
The Watchlist module adds a side panel for tracking symbol lists with live quotes. It is enabled by default when you call enableVelaPro(), and clicking any symbol row opens that symbol in the active chart.
Key features include:
- Multiple named watchlists with collapsible section headers and drag-and-drop row reordering.
- Symbol rows showing the last price, daily change, optional volume, and a one-month closing-price sparkline, with sortable column headers and gainers or losers filters.
- A symbol details pane beneath the list displaying the active chart symbol's daily range, open, high, low, and volume.
- A right-click context menu on each row to open the symbol on the chart, insert a section above, copy the ticker, remove the symbol, or trigger custom row actions.
- An expanded view covering the chart column with a daily briefing, multi-period performance metrics, a correlation matrix, and a full symbols table.
Configuration
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
enableVelaPro({
watchlist: {
defaultSymbols: ['BTCUSDT', 'ETHUSDT', 'SOLUSDT'],
rowActions: [
{
id: 'acme.research',
label: 'Open research',
run: (_ctx, symbol) => window.open(`/research/${encodeURIComponent(symbol)}`),
},
],
width: 360,
},
});
const workspace = new VelaWorkspace('#chart', {
layout: false,
symbol: 'BTCUSDT',
providers: { binance: () => new BinanceProvider() },
persist: true,
});Pass enableVelaPro({ watchlist: false }) to disable the module.
Options
| Option | Default | Description |
|---|---|---|
storage | new LocalWatchlistStorage() | WatchlistStorage adapter for persisting lists. Defaults to localStorage under the key velapro.watchlists. |
quotes | ProviderQuotes over chart providers | QuoteSource adapter supplying live quotes and daily bars. |
defaultSymbols | Cross-asset starter list | Initial symbols used when storage is empty. Pass [] to start with an empty list. |
rowActions | None | Custom entries appended to each symbol's right-click menu. Each item has id, label, optional icon, and run(ctx, symbol). |
width | 400 | Initial side panel width in pixels. Users can resize the panel between 240 and 820 pixels. |
order | 0 | Sort order among side rail panel buttons (0 places Watchlist first). |
When defaultSymbols is omitted, Vela Pro builds the initial list from a curated set of crypto, equity, ETF, futures, and forex tickers filtered to symbols supported by your registered providers and grouped into sections. If your providers match none of those tickers, the list starts with the active chart's symbol. Pass defaultSymbols to specify an explicit starter list.
With the default quotes implementation, each row reads from your chart data provider. Daily historical bars supply the previous close and session statistics, while the provider's daily bar subscription updates the last price in real time. Providers without subscribe are polled every 15 seconds. Quote subscriptions remain active only while the Watchlist panel is open.
Controller API
watchlistController() returns the page's WatchlistController instance after enableVelaPro() installs the module, or null before initialization.
import { watchlistController, watchlistModel } from '@luxalgo/vela-pro-watchlist';
const lists = watchlistController();
if (lists) {
if (!lists.has('SOLUSDT')) lists.add('SOLUSDT'); // append to the active list
lists.remove('XRPUSDT');
// Create and select a new watchlist.
lists.update((state) =>
watchlistModel.addList(state, 'Earnings week', [
{ kind: 'symbol', symbol: 'AAPL' },
{ kind: 'symbol', symbol: 'NVDA' },
]),
);
lists.onChange((state) => console.info(state.activeId, state.lists.length));
}add, remove, and has operate on the currently selected list. Structural mutations go through update(op), which applies a pure state transition (state: WatchlistState) => WatchlistState. The watchlistModel namespace exports built-in transitions including addList, renameList, deleteList, selectList, addSection, updateSection, removeSection, addSymbol, removeSymbol, and moveEntry. Call state() to read the current snapshot, and await ready to wait until initial storage loading completes.
Storage port
Implement WatchlistStorage to persist watchlists to your backend. Both load() and save() can return synchronously or return a Promise.
interface WatchlistStorage {
load(): WatchlistState | null | Promise<WatchlistState | null>;
save(state: WatchlistState): void | Promise<void>;
}
interface WatchlistState {
lists: Array<{ id: string; name: string; entries: WatchlistEntry[] }>;
activeId: string;
columns: Record<'price' | 'change' | 'changePercent' | 'volume', boolean>;
sparklines: boolean;
details: boolean;
}
type WatchlistEntry =
| { kind: 'symbol'; symbol: string }
| { kind: 'section'; id: string; title: string; collapsed?: boolean };Return null from load() when the user has no saved watchlists yet so the module initializes the default list. save(state) is called with the full WatchlistState (including visible column toggles, sparklines, and the details pane preference) after every modification.
import { enableVelaPro } from '@luxalgo/vela-pro';
import type { WatchlistState, WatchlistStorage } from '@luxalgo/vela-pro-watchlist';
let loaded = false;
const storage: WatchlistStorage = {
async load() {
const res = await fetch('/api/watchlists', { credentials: 'include' });
if (!res.ok && res.status !== 404) throw new Error(`Watchlists: HTTP ${res.status}`);
loaded = true;
return res.status === 404 ? null : ((await res.json()) as WatchlistState);
},
async save(state) {
if (!loaded) return;
await fetch('/api/watchlists', {
method: 'PUT',
credentials: 'include',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(state),
});
},
};
enableVelaPro({ watchlist: { storage } });If load() rejects, the module falls back to creating a fresh default list and invokes save() on the next user edit. Guarding save() with a loaded flag as shown above prevents a transient network failure on load from overwriting existing server data.
LocalWatchlistStorage(key) is the default browser implementation. MemoryWatchlistStorage stores state in memory for the current session only, which is useful for tests and stateless demos.
Custom quote source
Implement QuoteSource when quotes come from a dedicated market-data stream rather than from the chart's DataProvider.
interface QuoteSource {
/** Subscribe to live quotes for a symbol. Returns an unsubscribe function. */
watch(symbol: string, onQuote: (quote: Quote) => void): () => void;
/** Optional: return up to `count` daily bars in chronological order (oldest first). */
dailyBars?(symbol: string, count: number): Promise<readonly OHLCV[]>;
}Quote field | Type | Description |
|---|---|---|
symbol | string | Symbol string matching the watchlist entry |
last | number | null | Latest traded price |
prevClose | number | null | Previous session close used as the baseline for daily change |
open, high, low, volume | number | null | Current session OHLCV statistics |
change, changePercent | number | null | Daily net change and percentage change |
spark | number[] | Historical daily closes for the sparkline (oldest first) |
tick | number | Minimum price increment used to format displayed prices |
updated | number | Timestamp of the latest quote update in epoch milliseconds |
unresolved | boolean (optional) | When true, indicates no provider serves the symbol and renders placeholder dashes |
blankQuote(symbol) creates an empty Quote template, and withChange(quote) derives change and changePercent from last and prevClose.
import { blankQuote, enableVelaPro, withChange, type Quote, type QuoteSource } from '@luxalgo/vela-pro';
interface QuoteMessage {
last: number;
prevClose: number;
open: number;
high: number;
low: number;
volume: number;
}
class ServerQuotes implements QuoteSource {
watch(symbol: string, onQuote: (quote: Quote) => void): () => void {
const stream = new EventSource(`/api/quotes/${encodeURIComponent(symbol)}`);
stream.onmessage = (event) => {
const message = JSON.parse(String(event.data)) as QuoteMessage;
onQuote(withChange({ ...blankQuote(symbol), ...message, tick: 0.01, updated: Date.now() }));
};
return () => stream.close();
}
}
enableVelaPro({ watchlist: { quotes: new ServerQuotes() } });watch is called for each symbol in the active list using the exact string stored in the entry (such as BTCUSDT or binance:BTCUSDT). Its returned cleanup function runs when the panel closes or when the symbol is removed from the active list. Implement dailyBars if you enable the expanded view, since multi-period returns, drawdowns, and cross-asset correlations are computed from daily bars. See Quotes and market depth for quote handling across Vela Pro.
Widgets
You can mount both Watchlist surfaces outside a workspace as standalone components (see Standalone widgets). Both factories read controller and quotes once at creation and accept updated values for the remaining props via update(props).
createWatchlist(props) creates the compact panel widget. Its tools element contains the list selector, the Add symbol trigger, the settings menu, and the expand button.
| Prop | Description |
|---|---|
controller | Required. WatchlistController managing list state. |
quotes | Required. QuoteSource feeding row prices. |
directory | Accessor returning chart data (() => chart.data) for symbol descriptions, logos, and search indexing. Without it, rows display raw tickers. |
symbol | Currently active symbol highlighted in the list and shown in the details pane. |
host | Portal container for menus and popovers. Defaults to the widget's root element. |
rowActions | Function returning custom right-click menu actions with id, label, optional icon, and run(symbol). |
picker | Function returning a symbol picker dialog for Add symbol. Defaults to an inline search input when omitted. |
active | Controls visibility and quote subscriptions. When false, quote feeds are paused. Defaults to true. |
onSelectSymbol | Callback invoked when the user clicks a symbol row. |
onMaximize | Callback invoked when the user clicks the expand button. Omit to hide the expand button. |
createWatchlistView(props) creates the full-width expanded view. It accepts controller, quotes (implementing dailyBars), directory, symbol, host, and picker, along with onSelectSymbol, onMinimize, and onClose. The Add symbol, minimize, and close buttons render only when their corresponding props are provided.
Keyboard shortcuts
These shortcuts apply when the Watchlist panel has focus.
| Keys | Action |
|---|---|
| Up, Down | Select the previous or next symbol in the list and load it on the chart |
| Delete, Backspace | Remove the highlighted symbol from the active list |
In the expanded view's symbols table, Up, Down, Home, and End move focus between rows, Space toggles row selection, Enter opens the symbol on the chart, and X, Delete, or Backspace removes it. Pressing Escape clears the current selection or returns to the chart when nothing is selected.
Related
Overview
Configure Vela Pro's six domain modules, coordinate inter-module features, control state from code, and connect backend services through typed ports.
Alerts
Configure price and Pine Script® alerts, handle notification callbacks and webhooks, manage rules from code, and persist alerts to your server.