Custom panels and widgets
Register custom side panels, bottom dock panels, and side rail actions in a Vela Pro workspace using reusable widget components.
You can extend a Vela Pro workspace with custom side panels, bottom dock panels, and side rail action buttons using declarative registration descriptors. Vela Pro mounts your DOM elements into the shell layout and passes a live WidgetContext for reading chart state and dispatching workspace actions.
Follow two rules across every registration API on this page:
- Register before constructing workspaces:
VelaWorkspacesnapshots registered panels and actions during construction. If you register an action dynamically after construction, callworkspace.refreshActions(). - Read workspace state from the
ctxparameter:mountandruncallbacks execute per workspace instance and receive that workspace'sWidgetContext. Read the active chart, symbol, andhostelement fromctxrather than closing over an outer workspace reference so descriptors support multiple workspaces on the same page.
Writing a widget
Structure panel content using the same standalone widget pattern used by Vela Pro's built-in modules: a factory function accepting props and returning { el, update, destroy }. Keeping data inputs in props and user actions in callbacks keeps the widget decoupled from VelaWorkspace, so the same component can mount inside a side panel, inside the bottom dock, or on a standalone page.
export interface ResearchProps {
symbol?: string;
/** Optional click handler. When omitted, notes render as static text. */
onOpenNote?: (id: string) => void;
}
export function createResearch(props: ResearchProps = {}) {
let current = { ...props };
let request: AbortController | null = null;
const el = document.createElement('div');
el.className = 'acme-research';
const load = async (): Promise<void> => {
request?.abort();
const { signal } = (request = new AbortController());
if (!current.symbol) return;
const res = await fetch(`/api/research/${encodeURIComponent(current.symbol)}`, { signal });
const notes = (await res.json()) as Array<{ id: string; title: string }>;
el.replaceChildren(
...notes.map((note) => {
const row = document.createElement(current.onOpenNote ? 'button' : 'p');
row.textContent = note.title;
row.onclick = () => current.onOpenNote?.(note.id);
return row;
}),
);
};
const refresh = (): void => void load().catch(() => {}); // ignore aborted fetches
refresh();
return {
el,
update(next: Partial<ResearchProps>): void {
const moved = next.symbol !== undefined && next.symbol !== current.symbol;
current = { ...current, ...next };
if (moved) refresh();
},
destroy(): void {
request?.abort();
el.remove();
},
};
}Side panels
registerSidePanel is exported by the plugin SDK in Vela's open-source core (@luxalgo/vela/plugin). The workspace renders the panel header, close button, and side rail toggle button, passing the body container to mount. Setting placement: 'column' docks the panel as a full-height column beside the chart area, matching Vela Pro's built-in side panels.
import { registerIcon, registerSidePanel } from '@luxalgo/vela/plugin';
import { describeRailEntry } from '@luxalgo/vela-pro';
import { onActiveSymbol } from '@luxalgo/vela-pro/plugin';
// Standalone widget defined in the section above.
declare function createResearch(props: { symbol?: string; onOpenNote?: (id: string) => void }): {
el: HTMLElement;
update(next: { symbol?: string }): void;
destroy(): void;
};
export const RESEARCH_PANEL_ID = 'acme.research';
registerIcon('acme-research', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M4 2.5h8v11H4zM6 6h4M6 9h4"/></svg>');
describeRailEntry(RESEARCH_PANEL_ID, { description: 'Analyst notes for the symbol on the chart.' });
registerSidePanel({
id: RESEARCH_PANEL_ID,
title: 'Research',
icon: 'acme-research',
placement: 'column',
order: 6, // place after Vela Pro's built-in panels (orders 0 through 5)
width: 360,
resizable: true,
minWidth: 280,
maxWidth: 560,
mount: (ctx, body) => {
const research = createResearch({
symbol: ctx.symbol,
onOpenNote: (id) => window.open(`/research/notes/${encodeURIComponent(id)}`),
});
body.append(research.el);
// Fires immediately and whenever the active chart cell or its symbol changes.
const offSymbol = onActiveSymbol(ctx, (symbol) => research.update({ symbol }));
return {
destroy: () => {
offSymbol();
research.destroy();
},
};
},
});Registered side panels automatically appear on the side rail sorted by order. Calling describeRailEntry attaches hover-card description text to the rail button. To open or close the panel programmatically, call ctx.togglePanel('acme.research', true).
onActiveSymbol tracks the active cell across multi-chart layouts whenever focus moves to another chart. mount can also return onOpen (invoked when the panel becomes visible, ideal for deferring expensive network requests) and onChart (invoked when the active chart reference changes).
registerSidePanel also supports floating panels (overlay: true), a Maximize toggle (maximizable: true), and custom headers (header: 'none'). See Side panels and Layout regions in the core documentation for the complete descriptor schema.
You can mount any built-in module widget inside a custom panel using the same adapter pattern: instantiate the widget inside mount, pass ctx.host as host, synchronize props from ctx, and clean up in destroy. Reuse the installed module's controller (watchlistController(), tradingController()) so your custom panel stays synchronized with built-in surfaces (see Standalone widgets).
Bottom dock panels
The bottom dock is Vela Pro's collapsible panel region beneath the chart grid, hosting surfaces such as the trading panel and strategy tester. It displays one active panel at a time, supports top-edge drag resizing and full-column maximization, and persists its open panel ID and height in the workspace state document. Call registerBottomPanel to add a panel to the dock.
import { registerIcon } from '@luxalgo/vela/plugin';
import { registerBottomPanel } from '@luxalgo/vela-pro';
import { onActiveSymbol } from '@luxalgo/vela-pro/plugin';
registerIcon('acme-news', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M2.5 3.5h9v9h-9zM11.5 6h2v6.5h-2M5 6.5h4M5 9.5h4"/></svg>');
registerBottomPanel({
id: 'acme.news',
title: 'News',
icon: 'acme-news',
description: 'Headlines for the symbol on the chart.',
order: 30,
minHeight: 120,
collapseBelow: 160,
mount: (ctx, body, header) => {
const list = document.createElement('ul');
body.append(list);
let visible = false;
let symbol = '';
const load = async (): Promise<void> => {
const asked = symbol;
if (!visible || !asked) return;
const res = await fetch(`/api/news?symbol=${encodeURIComponent(asked)}`);
const headlines = (await res.json()) as string[];
if (asked !== symbol) return; // discard stale response if symbol changed mid-flight
list.replaceChildren(...headlines.map((text) => Object.assign(document.createElement('li'), { textContent: text })));
header.setCount(headlines.length);
};
const offSymbol = onActiveSymbol(ctx, (next) => {
symbol = next;
void load();
});
return {
onOpen: () => {
visible = true;
void load();
},
onClose: () => {
visible = false;
},
destroy: offSymbol,
};
},
});mount executes once per workspace when the bottom dock initializes rather than waiting for the first open, allowing panels to subscribe to background state while hidden. Defer network polling or heavy rendering to onOpen and pause it in onClose.
Bottom panels receive a toggle button on the side rail by default, and can be opened programmatically via bottomDock(ctx)?.open('acme.news').
| Descriptor field | Default | Description |
|---|---|---|
id | Required | Stable identifier persisted in the workspace state document when open. |
title, icon | Required | Panel title and side rail icon name. |
description | None | Hover-card description shown on the side rail button. |
order | 100 | Sort order among bottom panels and their rail buttons (Trading uses 10). |
rail | true | Adds a toggle button on the side rail. Pass false for panels opened exclusively from code (like the strategy tester). |
restoreOpen | Matches rail | Restores this panel on reload when saved state had it open. |
minHeight | 140 | Minimum dock height in pixels while this panel is active. |
collapseBelow | None | Drag threshold in pixels below which releasing the resize handle snaps the panel to its minimum height. |
chrome | 'header' | 'header' renders the standard dock title bar with maximize and close buttons; 'none' omits the title bar so the panel renders custom chrome inside body. |
mount(ctx, body, header) | Required | Populates body and optionally returns { onOpen, onClose, destroy }. |
The header argument passed to mount controls the dock frame for your panel:
| Member | Description |
|---|---|
slot | Right-aligned HTMLElement in the dock title bar for mounting compact panel controls while active. |
setCount(count) | Displays a numeric badge next to the panel title, or hides it when null. |
close() | Closes the bottom dock. |
isMaximized(), setMaximized(on) | Reads or toggles full-height maximization over the chart column. |
fold(height) | Locks the dock to a fixed height in pixels with resizing disabled while active, or restores resizing when null. |
When using chrome: 'none', wire your custom close and maximize controls to header.close() and header.setMaximized(...), and use header.fold(40) if your panel supports collapsing into a compact single-row bar.
bottomDock(ctx) returns the workspace's dock controller, or null when the bottom dock is disabled:
| Member | Description |
|---|---|
open(id?) | Opens the dock to id, or reopens the most recently viewed panel when id is omitted. |
close() | Closes the dock. |
toggle(id) | Opens id, or closes the dock if id is already active. |
setMaximized(on) | Expands the dock over the chart column or restores normal split height. |
isOpen, active | Current open state and active panel ID. |
onChange(listener) | Subscribes to open, close, and panel-switch events. Returns an unsubscribe function. |
Side rail items
Side panels and bottom panels register their side rail buttons automatically. Use registerRailItem to add a standalone action button to the side rail that runs custom logic instead of toggling a panel.
import { registerIcon } from '@luxalgo/vela/plugin';
import { registerRailItem } from '@luxalgo/vela-pro';
declare function openDepositDialog(host: HTMLElement): void;
registerIcon('acme-deposit', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M8 2.5v8M5 7.5l3 3 3-3M3 13.5h10"/></svg>');
registerRailItem({
id: 'acme.deposit',
title: 'Deposit',
icon: 'acme-deposit',
description: 'Add funds to your account.',
order: 50,
run: (ctx) => openDepositDialog(ctx.host),
});| Descriptor field | Description |
|---|---|
id | Unique action identifier used for ordering and filtering in sideRail layout options. |
title, icon | Accessible label and registered icon name. |
description, shortcut | Optional hover-card description and keyboard shortcut hint. |
order | Ascending sort order among rail items (defaults to 100). |
run(ctx) | Click handler invoked with the workspace's WidgetContext. |
active(ctx) | Optional predicate returning true when the button should render in its active/pressed state. |
subscribe(ctx, refresh) | Optional subscription hook that calls refresh() whenever active(ctx) changes and returns an unsubscribe function. |
Custom rail items appear in the lower rail group by default. You can customize rail grouping and visibility via enableVelaPro({ sideRail: { top, bottom, exclude } }); users cannot reorder or hide rail entries from the UI. Call sideRail(ctx)?.setBadge(id, count) to display an unread or activity badge on any panel or rail item button.
Under the hood, the side rail builds on the core sidebar (target: 'sidebar'). See The sidebar in the core documentation and Interface layout for rail placement options.
Related
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.
Custom modules
Author custom Vela Pro modules with definePlugin, declare module dependencies, consume TradingApi and AlertsApi, and expose typed module APIs.