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

Standalone widgets

Mount Vela Pro module widgets (Watchlist, Order Book, Order Ticket, Trading Panel, Journal, and Calendar) in custom layouts with or without a chart.

View as Markdown

Every Vela Pro module panel is built as a standalone widget factory that returns a DOM element and lifecycle methods. You can mount a watchlist in a custom terminal column, embed an order ticket inside an application modal, or render a market calendar on a page with no chart at all. Inside a VelaWorkspace, modules mount these same widgets into workspace panels.

import { DARK_THEME } from '@luxalgo/vela';
import { ensureUIHost } from '@luxalgo/vela/ui';
import { createCalendar, type CalendarSource } from '@luxalgo/vela-pro-calendar';

declare const source: CalendarSource;

const box = document.getElementById('calendar')!;
ensureUIHost(box, DARK_THEME);

const calendar = createCalendar({
    source,
    host: box,
    onSelectSymbol: (symbol) => window.location.assign(`/chart/${encodeURIComponent(symbol)}`),
});
box.append(calendar.el);

Standalone widgets do not require a chart instance or a call to enableVelaPro(). Each widget receives all required state and callbacks through its props.

Available widgets

FactoryPackageUI surfacetools header controls
createWatchlist(props)@luxalgo/vela-pro-watchlistSymbol lists, live quotes, and symbol detailsList selector, Add symbol, settings
createWatchlistView(props)@luxalgo/vela-pro-watchlistFull-width watchlist analytics viewNone
createOrderBook(props)@luxalgo/vela-pro-domDepth book, DOM ladder, and trades tapeVenue selector, price grouping, settings
createAlertsList(props)@luxalgo/vela-pro-alertsAlert rules and firing history logNone
createOrderTicket(props)@luxalgo/vela-pro-tradingInteractive order entry ticketNone
createTradingPanel(props)@luxalgo/vela-pro-tradingPositions, working orders, order history, and tradesNone
createJournalPanel(props)@luxalgo/vela-pro-journalCompact trading journal summaryAccount selector, Add trade, Maximize
createJournalView(props)@luxalgo/vela-pro-journalFull-screen trading journal dashboardNone
createCalendar(props)@luxalgo/vela-pro-calendarEconomic releases, corporate events, and holidaysImpact filter, refresh

See each module's widget reference for its full props table: Watchlist, Alerts, Order book, Trading, Journal, and Calendar.

Widget interface

MemberDescription
elRoot HTMLElement to mount in the DOM. Widgets fill their parent box, so mount el inside an explicitly sized container or a CSS Grid/Flexbox cell.
toolsOptional HTMLElement containing compact header controls. Renders in the widget's top bar by default, or can be reparented into your own panel header.
update(props)Updates mutable props after creation, such as symbol, active, or event callbacks.
destroy()Removes el from the DOM and tears down widget-owned subscriptions.

All Vela Pro widgets follow four lifecycle conventions:

  • Props in, callbacks out: Widgets never read from a chart directly. State enters through props (such as a controller, data source, and symbol) and user interactions leave through callbacks (onSelectSymbol, onOpenAlert, onMaximize, onShowTrade, onNotify).
  • Callback-driven controls: Optional UI buttons render only when their corresponding callback is supplied. Without onMaximize, the watchlist and journal panels hide Maximize; without onClose, the trading panel hides Close.
  • Visibility gating (active): Calling update({ active: false }) pauses live quote and depth subscriptions on the watchlist and order book until active returns to true, and clears any staged draft on the order ticket.
  • Explicit teardown (destroy()): destroy() unmounts the widget and closes its internal streams. Controllers and shared quote sources remain owned by host code; call trading.destroy() and quotes.dispose() when tearing down the page.

Host setup

Inside a VelaWorkspace, modules wire themes, controllers, and price feeds automatically. On a custom page, your host code provides that plumbing:

Provided by VelaWorkspaceHost setup on a custom page
Theme variables and overlay portal layerCall ensureUIHost(element, theme) once on a container and pass that element as each widget's host (see Theming).
Shared module controllersInstantiate one controller per module (WatchlistController, AlertsController, TradingController, JournalController, CalendarController) with its port.
Live quotesPass a QuoteSource, such as new ProviderQuotes(() => chart.data) over chart providers or a custom implementation.
Symbol metadata, logos, and depth feedsPass directory or icons as an accessor returning chart data (() => chart.data).
Active symbol updatesCall widget.update({ symbol }) on each widget whenever the selected symbol changes.
Live price ticks for paper fills and alertsCall trading.notePrice(symbol, price, time) and alerts.notePrice(symbol, price, barTime) on incoming ticks.
Broker-to-journal synchronizationCall journal.syncBroker(trading.broker) once at startup.

Widgets bound to the same controller instance share live state automatically. Passing a single TradingController to createOrderTicket, createTradingPanel, and createOrderBook keeps orders and positions synchronized across all three surfaces. Instantiate at most one controller per module per page, because two TradingController instances pointing at the same persisted paper storage key will overwrite each other.

If your page also calls enableVelaPro(), reuse the controllers already created by the installed modules (tradingController(), watchlistController(), alertsController(), journalController(), and calendarController()) rather than constructing duplicates. To mount custom or built-in widgets as panels inside VelaWorkspace itself, see Custom panels and widgets.

Full example

The example below arranges a watchlist, a VelaWorkspace chart, an order book, and an order ticket in a custom CSS Grid layout, sharing market data and paper trading state across all surfaces.

<div id="terminal">
    <div id="watchlist"></div>
    <div id="chart"></div>
    <div id="book"></div>
    <div id="ticket"></div>
</div>
#terminal {
    display: grid;
    grid-template: 1fr 1fr / 320px 1fr 340px;
    height: 100vh;
}
#terminal > * { min-width: 0; min-height: 0; overflow: hidden; }
#watchlist, #chart { grid-row: 1 / 3; }
import { DARK_THEME, type DataProvider } from '@luxalgo/vela';
import { ensureUIHost } from '@luxalgo/vela/ui';
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import type { DepthFeed } from '@luxalgo/vela-pro';
import { ProviderQuotes, onActiveSymbol } from '@luxalgo/vela-pro/plugin';
import { createOrderBook } from '@luxalgo/vela-pro-dom';
import { PaperBroker, TradingController, createOrderTicket } from '@luxalgo/vela-pro-trading';
import { LocalWatchlistStorage, WatchlistController, createWatchlist } from '@luxalgo/vela-pro-watchlist';

// Custom data provider serving OHLCV candles and DepthFeed streams.
declare const MyProvider: new () => DataProvider & DepthFeed;

const page = document.getElementById('terminal')!;
ensureUIHost(page, DARK_THEME);

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    live: true,
    providers: { acme: () => new MyProvider() },
});
const ctx = workspace.context();
const data = () => ctx.chart.data; // symbol metadata, logos, quotes, and depth streams

// Instantiate one controller per module.
const quotes = new ProviderQuotes(data);
const lists = new WatchlistController({ storage: new LocalWatchlistStorage() });
const trading = new TradingController({ broker: new PaperBroker() });

const openSymbol = (symbol: string): void => ctx.setSymbol(symbol);
const watchlist = createWatchlist({ controller: lists, quotes, directory: data, host: page, onSelectSymbol: openSymbol });
const book = createOrderBook({ directory: data, host: page, trading: () => trading });
const ticket = createOrderTicket({ controller: trading, host: page, active: true });
document.getElementById('watchlist')!.append(watchlist.el);
document.getElementById('book')!.append(book.el);
document.getElementById('ticket')!.append(ticket.el);

// Keep every widget synchronized with the active chart symbol and forward live ticks to the paper broker.
let offBar = (): void => {};
onActiveSymbol(ctx, (symbol, chart) => {
    for (const widget of [watchlist, book, ticket]) widget.update({ symbol });
    offBar();
    offBar = chart?.on('bar', (bar) => trading.notePrice(symbol, bar.close, bar.time)) ?? ((): void => {});
});

Key integration details in this setup:

  • ensureUIHost applies UI kit theme tokens to #terminal and creates a portal layer for menus and dialogs so popovers inherit theme styling.
  • ProviderQuotes and onActiveSymbol are imported from @luxalgo/vela-pro/plugin. onActiveSymbol fires immediately with the initial symbol and active chart, then re-fires whenever the active cell or symbol changes.
  • Passing trading: () => trading connects DOM ladder click-trading, order cancellation, and position closing to the same TradingController used by the order ticket. Omit trading for a read-only order book.
  • Forwarding 'bar' updates into trading.notePrice marks open positions and triggers simulated PaperBroker fills.

Synchronizing widgets

Desired interactionIntegration wiring
Clicking a watchlist row or position loads the chartonSelectSymbol: (symbol) => ctx.setSymbol(symbol)
Widgets follow active chart symbol changesonActiveSymbol(ctx, (symbol) => widget.update({ symbol }))
DOM ladder places, cancels, and closes orderscreateOrderBook({ trading: () => trading })
Paper orders fill and price alerts evaluateCall notePrice(symbol, bar.close, bar.time) on TradingController and AlertsController inside chart.on('bar', ...)
Journal records executions from the trading accountjournal.syncBroker(trading.broker)
Alerts list opens the alert editor dialogonOpenAlert: (seed) => openAlertDialog(ctx, alerts, seed)
Watchlist row context menu creates an alertAdd a rowActions item whose run(symbol) calls openAlertDialog(ctx, alerts, { symbol })
Watchlist or journal expands to full-screen viewSupply onMaximize and mount createWatchlistView or createJournalView in an overlay container

ctx is the WidgetContext returned by workspace.context(), which is required when opening the built-in openAlertDialog editor.

On this page