Module SDK
API reference for @luxalgo/vela-pro/plugin, including definePlugin, plugin context, and panel and UI helpers.
This page documents @luxalgo/vela-pro/plugin, the SDK entry point used to author Vela Pro modules. It covers definePlugin, the installation context, cross-module API contracts (TradingApi and AlertsApi), and shared panel, menu, and UI helpers. In code, modules use the plugin naming convention (definePlugin, VelaProPlugin, and the plugins option on enableVelaPro()).
Import symbols on this page from @luxalgo/vela-pro/plugin unless noted otherwise on the entry. Related guides: Custom modules, Custom panels and widgets.
Functions
assertVelaSdk
function assertVelaSdk(): voidattachHoverCard
Show a hover card for trigger while the pointer rests on it. Returns the detach.
function attachHoverCard(
trigger: HTMLElement,
content: () => HoverCardContent | null,
opts: HoverCardOptions,
): () => void
// Unexported supporting type referenced above
type HoverCardOptions = AttachHoverCardOptions;From @luxalgo/vela-ui/hover-card: AttachHoverCardOptions, HoverCardContent.
badge
function badge(
text: string,
tone?: 'buy' | 'sell' | 'profit' | 'loss' | 'accent' | 'solid',
): HTMLElementbareTicker
The bare ticker of BINANCE:BTCUSDT-style symbols.
function bareTicker(symbol: string): stringbutton
function button(opts: ButtonOptions): HTMLButtonElement
// Unexported supporting types referenced above
interface ButtonOptions {
label?: string;
icon?: string;
variant?: ButtonVariant;
size?: ButtonSize;
title?: string;
part?: string;
onClick?: (e: MouseEvent) => void;
}
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonVariant = 'ghost' | 'outline' | 'solid' | 'buy' | 'sell' | 'danger';checkbox
The kit's checkbox with its label beside it: the label names the box's input, so a press on either toggles it. The box is a fixed-size control of its own, never a container.
function checkbox(
label: string,
checked: boolean,
onChange?: (v: boolean) => void,
part?: string,
): LabeledCheckbox
// Unexported supporting type referenced above
interface LabeledCheckbox {
readonly el: HTMLElement;
readonly checked: boolean;
setChecked(checked: boolean): void;
destroy(): void;
}Default: part = 'checkbox'.
definePlugin
Type a plugin's API from its install; it returns plugin unchanged.
function definePlugin<Api>(plugin: VelaProPlugin<Api>): VelaProPlugin<Api>See also: VelaProPlugin.
drawArea
Shade the band between two prices across the visible chart.
function drawArea(low: number, high: number, text: string): PriceActionDescriptorSee also: PriceActionDescriptor.
eachChart
Run bind for every chart of the shell, now and as charts appear; the function it returns runs when that chart leaves the shell. Returns the stop.
function eachChart(ctx: WidgetContext, bind: Binder): () => void
// Unexported supporting types referenced above
type Binder = (c: ShellChart) => (() => void) | void;
interface ShellChart {
id: string;
chart: Chart;
}
type Chart = WidgetContext['chart'];From @luxalgo/vela/plugin: WidgetContext.
emptyState
function emptyState(opts: EmptyStateOptions): HTMLElement
// Unexported supporting type referenced above
type EmptyStateOptions = Omit<EmptyProps, 'className'>;From @luxalgo/vela-ui/empty: EmptyProps.
field
A title over its control.
function field(label: string, control: FieldControl, part?: string): HTMLElement
// Unexported supporting type referenced above
type FieldControl = HTMLElement | { readonly el: HTMLElement; readonly input?: HTMLElement };Default: part = 'field'.
guessTick
A tick size that suits a price when the market did not report one.
function guessTick(price: number | undefined): numberinjectProStyles
Inject one of Pro's stylesheets once per root. The CSS writes its layer itself (css`@layer vela.pro { … }`), so stylelint sees it.
function injectProStyles(
id: string,
css: string,
root?: Document | ShadowRoot,
): HTMLStyleElement | nullDefault: root = document.
input
A one-line text field, the kit's: read .value (the committed text), mount .el.
function input(opts?: InputFieldOptions): Input
// Unexported supporting type referenced above
interface InputFieldOptions {
value?: string;
placeholder?: string;
type?: InputType;
inputMode?: string;
part?: string;
onInput?: (value: string) => void;
onChange?: (value: string) => void;
}From @luxalgo/vela-ui/input: Input, InputType.
kbd
function kbd(text: string): HTMLElementlistingsElsewhere
Where else symbol trades in the same market (spot with spot, perpetual with perpetual): the listings whose books can stand in for or add to its own. Empty when the pool does not know it.
function listingsElsewhere(
symbol: string,
pool: readonly SymbolDescriptor[],
max?: number,
): Listing[]Default: max = 6.
See also: Listing. From @luxalgo/vela/plugin: SymbolDescriptor.
onActiveChart
Follow the chart the shell's chrome acts on (the active cell's). Called at once.
function onActiveChart(ctx: WidgetContext, cb: (chart: Chart | null) => void): () => void
// Unexported supporting type referenced above
type Chart = WidgetContext['chart'];From @luxalgo/vela/plugin: WidgetContext.
onActiveSymbol
Follow the symbol the shell's chrome acts on: the active chart's, as it changes. Called at once.
function onActiveSymbol(
ctx: WidgetContext,
cb: (symbol: string, chart: Chart | null) => void,
): () => void
// Unexported supporting type referenced above
type Chart = WidgetContext['chart'];From @luxalgo/vela/plugin: WidgetContext.
openPriceActions
Open the price actions for t at the pointer.
function openPriceActions(
e: MouseEvent,
t: PriceActionTarget,
extra?: readonly PriceActionDescriptor[],
): DropdownMenu | null
// Unexported supporting type referenced above
interface PriceActionTarget {
ctx: WidgetContext;
symbol: string;
price: number;
text: string;
}See also: PriceActionDescriptor. From @luxalgo/vela-ui/dropdown-menu: DropdownMenu. From @luxalgo/vela/plugin: WidgetContext.
ownPanelTitle
The panel around slot (its header slot) draws its own title there: the shell's title steps aside and the header takes the taller, borderless shape. Returns the undo.
function ownPanelTitle(slot: HTMLElement): () => voidpanelDock
The dock view of one shell.
function panelDock(ctx: WidgetContext): PanelDockView
// Unexported supporting types referenced above
interface PanelDockView {
list(): DockPanel[];
openId(): string | null;
toggle(id: string, open?: boolean): void;
onChange(cb: () => void): () => void;
hostToggles(): () => void;
destroy(): void;
}
interface DockPanel {
id: string;
title: string;
icon: string;
order: number;
builtIn: boolean;
}From @luxalgo/vela/plugin: WidgetContext.
registerPriceAction
Register (or replace) a price action. Returns the unregister.
function registerPriceAction(desc: PriceActionDescriptor): () => voidSee also: PriceActionDescriptor.
setButtonText
A new label for a button made by button.
function setButtonText(el: HTMLButtonElement, text: string): voidshowTradeHighlight
Flash h on the active chart for a few seconds. The highlight rides a native indicator that leaves the chart when the flash ends, so it never lands in the saved layout.
function showTradeHighlight(ctx: WidgetContext, h: TradeHighlight): void
// Unexported supporting type referenced above
interface TradeHighlight {
time: number;
price: number;
title: string;
when: string;
}From @luxalgo/vela/plugin: WidgetContext.
sparkline
function sparkline(values: readonly number[], opts?: SparklineOptions): SVGSVGElement
// Unexported supporting type referenced above
interface SparklineOptions {
width?: number;
height?: number;
area?: boolean;
baseline?: number | null;
part?: string;
}stat
function stat(label: string, value?: string, tone?: Tone, sub?: string): StatHandle
// Unexported supporting types referenced above
interface StatHandle {
el: HTMLElement;
set(value: string, tone?: Tone, sub?: string | null): void;
}
type Tone = 'profit' | 'loss' | null;Defaults: value = '—', tone = null.
symbolLogo
function symbolLogo(icons: SymbolIcons | null, symbol: string, part?: string): HTMLElementDefault: part = 'logo'.
See also: SymbolIcons.
takeOverBell
Route the bell's press to onPress, or hide the bell when onPress is null.
function takeOverBell(ctx: WidgetContext, onPress: (() => void) | null): () => voidFrom @luxalgo/vela/plugin: WidgetContext.
textArea
A multi-line text field, the kit's: read .value (committed on blur), mount .el.
function textArea(opts?: { value?: string; placeholder?: string; rows?: number; part?: string; onInput?: (value: string) => void }): TextAreaFrom @luxalgo/vela-ui/text-area: TextArea.
tickFromSymbolInfo
A tick size from a provider's symbol info (mintick, else 1 / pricescale).
function tickFromSymbolInfo(info: unknown): number | nulltoneOf
function toneOf(n: number): Tone
// Unexported supporting type referenced above
type Tone = 'profit' | 'loss' | null;underStatusline
Keep el under the status line of canvas's chart.
function underStatusline(canvas: HTMLElement, el: HTMLElement): UnderStatuslineSee also: UnderStatusline.
Classes
BarChart
class BarChart {
constructor(opts?: BarChartOptions);
readonly el: HTMLElement;
setData(data: readonly BarDatum[], refs?: ReadonlyArray<{ at: number; color: string }>): void;
destroy(): void;
}
// Unexported supporting type referenced above
type BarChartOptions = NonNullable<Parameters<typeof createBarChart>[0]> & { part?: string };| Member | Type | Description |
|---|---|---|
constructor | (opts?: BarChartOptions) | |
el | HTMLElement | |
setData() | (data: readonly BarDatum[], refs?: ReadonlyArray<{ at: number; color: string }>) => void | refs are dashed vertical markers at fractional bar positions. |
destroy() | () => void |
From @luxalgo/vela-ui/bar-chart: BarDatum.
Dropdown
A choice among options: the kit's Select, a trigger showing the chosen label over a list.
class Dropdown {
constructor(opts: DropdownOptions);
readonly el: HTMLElement;
readonly value: string;
setValue(value: string): void;
destroy(): void;
}
// Unexported supporting types referenced above
interface DropdownOptions {
options: readonly DropdownOption[];
value: string;
onChange?: (value: string) => void;
size?: 'sm' | 'md';
part?: string;
label?: string;
host?: HTMLElement;
}
interface DropdownOption {
value: string;
label: string;
}LineChart
class LineChart {
constructor(opts?: LineChartOptions);
readonly el: HTMLElement;
setData(points: readonly LinePoint[]): void;
setAxes(on: boolean): void;
destroy(): void;
}
// Unexported supporting type referenced above
type LineChartOptions = NonNullable<Parameters<typeof createLineChart>[0]> & { part?: string };From @luxalgo/vela-ui/line-chart: LinePoint.
MenuToggle
class MenuToggle {
readonly isOpen: boolean;
toggle(anchor: HTMLElement, opts: MenuToggleOptions): void;
setItems(items: readonly MenuItemDescriptor[]): void;
destroy(): void;
}
// Unexported supporting type referenced above
interface MenuToggleOptions {
items: readonly MenuItemDescriptor[];
onSelect?: (id: string) => void;
host?: HTMLElement;
minWidth?: string;
align?: 'start' | 'end';
}| Member | Type | Description |
|---|---|---|
isOpen | boolean | |
toggle() | (anchor: HTMLElement, opts: MenuToggleOptions) => void | Open the menu under anchor, or close it when that button's menu is open (or recently closed). |
setItems() | (items: readonly MenuItemDescriptor[]) => void | Swap the open menu's items (a checked state changed). |
destroy() | () => void |
From @luxalgo/vela-ui/dropdown-menu: MenuItemDescriptor.
Segmented
One choice among a few options, on the kit's toggle group.
class Segmented {
constructor(opts: SegmentedOptions);
readonly el: HTMLElement;
readonly value: string;
set(value: string, notify?: boolean): void;
}
// Unexported supporting types referenced above
interface SegmentedOptions {
options: readonly SegmentedOption[];
value: string;
onChange?: (value: string) => void;
tone?: 'trade';
stretch?: boolean;
part?: string;
}
interface SegmentedOption {
value: string;
label: string;
icon?: string;
title?: string;
}Default: set(notify = false).
Interfaces and types
AlertsApi
What the alerts plugin offers others.
Also exported from @luxalgo/vela-pro.
interface AlertsApi {
open(ctx: WidgetContext, init: { symbol: string; price?: number }): void;
}| Member | Type | Description |
|---|---|---|
open() | (ctx: WidgetContext, init: { symbol: string; price?: number }) => void | Open the new-alert dialog for symbol, at price or the last price seen. |
From @luxalgo/vela/plugin: WidgetContext.
Listing
A listing of the same instrument, as listingsElsewhere gives it.
interface Listing {
symbol: string;
venue: string;
market: string;
}| Member | Type | Description |
|---|---|---|
symbol | string | Venue-pinned (COINBASE:BTC-USD). |
venue | string | |
market | string | Spot, Perpetual… |
PluginApis
The APIs typed for every plugin, so using one needs no dependency on its package.
Also exported from @luxalgo/vela-pro.
interface PluginApis {
trading: TradingApi;
alerts: AlertsApi;
}See also: AlertsApi, TradingApi.
PluginRegistry
Also exported from @luxalgo/vela-pro.
interface PluginRegistry {
get<K extends keyof PluginApis>(id: K): PluginApis[K] | undefined;
get<T = unknown>(id: string): T | undefined;
has(id: string): boolean;
}| Member | Type | Description |
|---|---|---|
get() | <K extends keyof PluginApis>(id: K) => PluginApis[K] | undefined | |
get() | <T = unknown>(id: string) => T | undefined | Another plugin's API, typed by its own package (a plugin it requires). |
has() | (id: string) => boolean | Whether a plugin with this id is installed. |
See also: PluginApis.
PriceActionDescriptor
interface PriceActionDescriptor {
id: string;
section: 'draw' | 'alert' | 'trade';
order?: number;
icon?: string;
label(t: PriceActionTarget): string;
when?(t: PriceActionTarget): boolean;
run(t: PriceActionTarget): void;
}
// Unexported supporting type referenced above
interface PriceActionTarget {
ctx: WidgetContext;
symbol: string;
price: number;
text: string;
}| Member | Type | Description |
|---|---|---|
id | string | |
section | 'draw' | 'alert' | 'trade' | Rows group by section, in this order, a separator between groups. |
order? | number | Order within the section (ascending, default 0). |
icon? | string | |
label() | (t: PriceActionTarget) => string | |
when?() | (t: PriceActionTarget) => boolean | |
run() | (t: PriceActionTarget) => void |
From @luxalgo/vela/plugin: WidgetContext.
SymbolIcons
Where logos come from: a shell (its chart's data), or anything that answers symbolIcon.
type SymbolIcons =
| { symbolIcon(symbol: string): string | null | undefined }
| Pick<WidgetContext, 'chart'>;From @luxalgo/vela/plugin: WidgetContext.
TradingApi
What the trading plugin offers others: its orders and positions, and trading from another surface.
Also exported from @luxalgo/vela-pro.
interface TradingApi {
onChange(listener: () => void): () => void;
state(): { readonly orders: readonly TradingApiOrder[]; readonly positions: readonly TradingApiPosition[]; readonly account: { readonly currency: string } };
trade(symbol: string, side: 'buy' | 'sell', opts?: { price?: number; qty?: number }): void;
cancelOrder(orderId: string): Promise<boolean>;
cancelAll(symbol?: string): Promise<boolean>;
closePosition(symbol: string, qty?: number): Promise<boolean>;
readonly broker: object;
}| Member | Type | Description |
|---|---|---|
onChange() | (listener: () => void) => () => void | Called after every change of state(). Returns the unsubscribe. |
state() | () => { readonly orders: readonly TradingApiOrder[]; … (truncated; see declaration) | |
trade() | (symbol: string, side: 'buy' | 'sell', opts?: { price?: number; qty?: number }) => void | Trade symbol, through the order ticket or straight away, as the user set it up. |
cancelOrder() | (orderId: string) => Promise<boolean> | Resolves false when the broker refused or failed; the trading plugin tells the user why. |
cancelAll() | (symbol?: string) => Promise<boolean> | Cancel the working orders, of symbol only when given. |
closePosition() | (symbol: string, qty?: number) => Promise<boolean> | Close symbol's position at market, all of it or qty. |
broker | object | The broker trading drives; its type ships with the trading plugin. |
See also: TradingApiOrder, TradingApiPosition.
TradingApiOrder
A working order, as the trading plugin reports it to other plugins.
interface TradingApiOrder {
readonly id: string;
readonly symbol: string;
readonly side: 'buy' | 'sell';
readonly qty: number;
readonly filledQty: number;
readonly limitPrice?: number;
readonly stopPrice?: number;
}TradingApiPosition
An open position, as the trading plugin reports it to other plugins.
interface TradingApiPosition {
readonly symbol: string;
readonly qty: number;
readonly avgPrice: number;
readonly unrealizedPnl?: number;
}| Member | Type | Description |
|---|---|---|
symbol | string | |
qty | number | Signed: long above zero, short below. |
avgPrice | number | |
unrealizedPnl? | number |
UnderStatusline interface
interface UnderStatusline {
update(height: number): void;
destroy(): void;
}| Member | Type | Description |
|---|---|---|
update() | (height: number) => void | Re-place after the status line moved or changed height; height 0 releases the legend. |
destroy() | () => void |
VelaProPlugin
Also exported from @luxalgo/vela-pro.
interface VelaProPlugin<Api = unknown> {
readonly id: string;
readonly requires?: readonly string[];
install(ctx: VelaProPluginContext): Api | void;
}| Member | Type | Description |
|---|---|---|
id | string | Its name, unique on the page: ctx.plugins.get(id) returns its API. |
requires? | readonly string[] | Plugins it cannot work without. They install first; without them it does not install. |
install() | (ctx: VelaProPluginContext) => Api | void | Called once, by enableVelaPro, before charts are built. What it returns is its API. |
See also: VelaProPluginContext.
VelaProPluginContext
Also exported from @luxalgo/vela-pro.
interface VelaProPluginContext {
readonly plugins: PluginRegistry;
}See also: PluginRegistry.
Constants
ALERT_LINE
Alert lines and their price tags on the chart.
const ALERT_LINE: '#f5a524';COMPARE_A
Two performances side by side (the journal's comparisons): blue against orange stays legible to colorblind readers and never reads as profit or loss.
const COMPARE_A: '#1197e2';COMPARE_B
const COMPARE_B: '#f59e0b';COMPARE_LINES
The watchlist's comparison lines, one per highlighted symbol.
const COMPARE_LINES: readonly string[];COPY_PRICE
const COPY_PRICE: PriceActionDescriptor;See also: PriceActionDescriptor.
DRAW_LINE
Draw a horizontal line at the price on the chart.
const DRAW_LINE: PriceActionDescriptor;See also: PriceActionDescriptor.
INK_DEEP
The darkest ink, for labels on very light fills.
const INK_DEEP: '#0b0e14';INK_LIGHT
Ink on dark plates (chart tags, trade lines' values).
const INK_LIGHT: '#f0f3fa';MOVES_OPPOSITE
const MOVES_OPPOSITE: '#e8913f';MOVES_TOGETHER
Correlation with a focus symbol: moving with it, and against it.
const MOVES_TOGETHER: '#4d7cfe';SESSION_ARC
The watchlist's session arc and its legend swatch.
const SESSION_ARC: '#699cff';TRADE_NEUTRAL
A trade line with no side (a draft before its side is known).
const TRADE_NEUTRAL: '#6a6d78';Re-exports
The following symbols are re-exported from the listed import path and documented on their primary reference page or in their upstream package.
| Export | Kind | Exported from | Documented in |
|---|---|---|---|
blankQuote | function | @luxalgo/vela-pro/plugin | Data feeds |
BookLevel | interface | @luxalgo/vela-pro/plugin | Data feeds |
BookSnapshot | interface | @luxalgo/vela-pro/plugin | Data feeds |
BottomPanelHeader | interface | @luxalgo/vela-pro/plugin | Layout and panels |
decimalsOf | function | @luxalgo/vela-pro/plugin | Layout and panels |
DepthSubscription | interface | @luxalgo/vela-pro/plugin | Data feeds |
describeRailEntry | function | @luxalgo/vela-pro/plugin | Layout and panels |
Disposer | class | @luxalgo/vela-pro/plugin | Layout and panels |
ensureProUi | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatClock | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatCompact | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatDateTime | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatDuration | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatMoney | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatPercent | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatPrice | function | @luxalgo/vela-pro/plugin | Layout and panels |
formatQty | function | @luxalgo/vela-pro/plugin | Layout and panels |
groupLevels | function | @luxalgo/vela-pro/plugin | Data feeds |
h | function | @luxalgo/vela-pro/plugin | Layout and panels |
hasDepthFeed | function | @luxalgo/vela-pro/plugin | Data feeds |
icon | function | @luxalgo/vela-pro/plugin | Layout and panels |
ProviderQuotes | class | @luxalgo/vela-pro/plugin | Data feeds |
Quote | interface | @luxalgo/vela-pro/plugin | Data feeds |
QuoteSource | interface | @luxalgo/vela-pro/plugin | Data feeds |
registerBottomPanel | function | @luxalgo/vela-pro/plugin | Layout and panels |
registerProIcons | function | @luxalgo/vela-pro/plugin | Layout and panels |
sideRail | function | @luxalgo/vela-pro/plugin | Layout and panels |
symbolPicker | function | @luxalgo/vela-pro/plugin | Symbols |
SymbolPickerLike | interface | @luxalgo/vela-pro/plugin | Symbols |
TapeTrade | interface | @luxalgo/vela-pro/plugin | Data feeds |
timeframeMs | function | @luxalgo/vela-pro/plugin | Replay and strategy |
withChange | function | @luxalgo/vela-pro/plugin | Data feeds |