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.
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
| Factory | Package | UI surface | tools header controls |
|---|---|---|---|
createWatchlist(props) | @luxalgo/vela-pro-watchlist | Symbol lists, live quotes, and symbol details | List selector, Add symbol, settings |
createWatchlistView(props) | @luxalgo/vela-pro-watchlist | Full-width watchlist analytics view | None |
createOrderBook(props) | @luxalgo/vela-pro-dom | Depth book, DOM ladder, and trades tape | Venue selector, price grouping, settings |
createAlertsList(props) | @luxalgo/vela-pro-alerts | Alert rules and firing history log | None |
createOrderTicket(props) | @luxalgo/vela-pro-trading | Interactive order entry ticket | None |
createTradingPanel(props) | @luxalgo/vela-pro-trading | Positions, working orders, order history, and trades | None |
createJournalPanel(props) | @luxalgo/vela-pro-journal | Compact trading journal summary | Account selector, Add trade, Maximize |
createJournalView(props) | @luxalgo/vela-pro-journal | Full-screen trading journal dashboard | None |
createCalendar(props) | @luxalgo/vela-pro-calendar | Economic releases, corporate events, and holidays | Impact filter, refresh |
See each module's widget reference for its full props table: Watchlist, Alerts, Order book, Trading, Journal, and Calendar.
Widget interface
| Member | Description |
|---|---|
el | Root 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. |
tools | Optional 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, andsymbol) 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; withoutonClose, the trading panel hides Close. - Visibility gating (
active): Callingupdate({ active: false })pauses live quote and depth subscriptions on the watchlist and order book untilactivereturns totrue, 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; calltrading.destroy()andquotes.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 VelaWorkspace | Host setup on a custom page |
|---|---|
| Theme variables and overlay portal layer | Call ensureUIHost(element, theme) once on a container and pass that element as each widget's host (see Theming). |
| Shared module controllers | Instantiate one controller per module (WatchlistController, AlertsController, TradingController, JournalController, CalendarController) with its port. |
| Live quotes | Pass a QuoteSource, such as new ProviderQuotes(() => chart.data) over chart providers or a custom implementation. |
| Symbol metadata, logos, and depth feeds | Pass directory or icons as an accessor returning chart data (() => chart.data). |
| Active symbol updates | Call widget.update({ symbol }) on each widget whenever the selected symbol changes. |
| Live price ticks for paper fills and alerts | Call trading.notePrice(symbol, price, time) and alerts.notePrice(symbol, price, barTime) on incoming ticks. |
| Broker-to-journal synchronization | Call 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:
ensureUIHostapplies UI kit theme tokens to#terminaland creates a portal layer for menus and dialogs so popovers inherit theme styling.ProviderQuotesandonActiveSymbolare imported from@luxalgo/vela-pro/plugin.onActiveSymbolfires immediately with the initial symbol and active chart, then re-fires whenever the active cell or symbol changes.- Passing
trading: () => tradingconnects DOM ladder click-trading, order cancellation, and position closing to the sameTradingControllerused by the order ticket. Omittradingfor a read-only order book. - Forwarding
'bar'updates intotrading.notePricemarks open positions and triggers simulatedPaperBrokerfills.
Synchronizing widgets
| Desired interaction | Integration wiring |
|---|---|
| Clicking a watchlist row or position loads the chart | onSelectSymbol: (symbol) => ctx.setSymbol(symbol) |
| Widgets follow active chart symbol changes | onActiveSymbol(ctx, (symbol) => widget.update({ symbol })) |
| DOM ladder places, cancels, and closes orders | createOrderBook({ trading: () => trading }) |
| Paper orders fill and price alerts evaluate | Call notePrice(symbol, bar.close, bar.time) on TradingController and AlertsController inside chart.on('bar', ...) |
| Journal records executions from the trading account | journal.syncBroker(trading.broker) |
| Alerts list opens the alert editor dialog | onOpenAlert: (seed) => openAlertDialog(ctx, alerts, seed) |
| Watchlist row context menu creates an alert | Add a rowActions item whose run(symbol) calls openAlertDialog(ctx, alerts, { symbol }) |
| Watchlist or journal expands to full-screen view | Supply 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.
Related
Broker integration
Implement the Broker port interface to connect order execution, account state streaming, position management, and multi-account switching to your brokerage.
Custom panels and widgets
Register custom side panels, bottom dock panels, and side rail actions in a Vela Pro workspace using reusable widget components.