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

Module SDK

API reference for @luxalgo/vela-pro/plugin, including definePlugin, plugin context, and panel and UI helpers.

View as Markdown

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(): void

attachHoverCard

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',
): HTMLElement

bareTicker

The bare ticker of BINANCE:BTCUSDT-style symbols.

function bareTicker(symbol: string): string

button

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): PriceActionDescriptor

See 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): number

injectProStyles

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 | null

Default: 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): HTMLElement

listingsElsewhere

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): () => void

panelDock

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): () => void

See also: PriceActionDescriptor.

setButtonText

A new label for a button made by button.

function setButtonText(el: HTMLButtonElement, text: string): void

showTradeHighlight

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.

function symbolLogo(icons: SymbolIcons | null, symbol: string, part?: string): HTMLElement

Default: 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): () => void

From @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 }): TextArea

From @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 | null

toneOf

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): UnderStatusline

See 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 };
MemberTypeDescription
constructor(opts?: BarChartOptions)
elHTMLElement
setData()(data: readonly BarDatum[], refs?: ReadonlyArray<{ at: number; color: string }>) => voidrefs are dashed vertical markers at fractional bar positions.
destroy()() => void

From @luxalgo/vela-ui/bar-chart: BarDatum.

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.

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';
}
MemberTypeDescription
isOpenboolean
toggle()(anchor: HTMLElement, opts: MenuToggleOptions) => voidOpen the menu under anchor, or close it when that button's menu is open (or recently closed).
setItems()(items: readonly MenuItemDescriptor[]) => voidSwap 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;
}
MemberTypeDescription
open()(ctx: WidgetContext, init: { symbol: string; price?: number }) => voidOpen 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;
}
MemberTypeDescription
symbolstringVenue-pinned (COINBASE:BTC-USD).
venuestring
marketstringSpot, 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;
}
MemberTypeDescription
get()<K extends keyof PluginApis>(id: K) => PluginApis[K] | undefined
get()<T = unknown>(id: string) => T | undefinedAnother plugin's API, typed by its own package (a plugin it requires).
has()(id: string) => booleanWhether 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;
}
MemberTypeDescription
idstring
section'draw' | 'alert' | 'trade'Rows group by section, in this order, a separator between groups.
order?numberOrder 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;
}
MemberTypeDescription
onChange()(listener: () => void) => () => voidCalled 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 }) => voidTrade 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.
brokerobjectThe 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;
}
MemberTypeDescription
symbolstring
qtynumberSigned: long above zero, short below.
avgPricenumber
unrealizedPnl?number

UnderStatusline interface

interface UnderStatusline {
    update(height: number): void;
    destroy(): void;
}
MemberTypeDescription
update()(height: number) => voidRe-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;
}
MemberTypeDescription
idstringIts 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 | voidCalled 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.

ExportKindExported fromDocumented in
blankQuotefunction@luxalgo/vela-pro/pluginData feeds
BookLevelinterface@luxalgo/vela-pro/pluginData feeds
BookSnapshotinterface@luxalgo/vela-pro/pluginData feeds
BottomPanelHeaderinterface@luxalgo/vela-pro/pluginLayout and panels
decimalsOffunction@luxalgo/vela-pro/pluginLayout and panels
DepthSubscriptioninterface@luxalgo/vela-pro/pluginData feeds
describeRailEntryfunction@luxalgo/vela-pro/pluginLayout and panels
Disposerclass@luxalgo/vela-pro/pluginLayout and panels
ensureProUifunction@luxalgo/vela-pro/pluginLayout and panels
formatClockfunction@luxalgo/vela-pro/pluginLayout and panels
formatCompactfunction@luxalgo/vela-pro/pluginLayout and panels
formatDateTimefunction@luxalgo/vela-pro/pluginLayout and panels
formatDurationfunction@luxalgo/vela-pro/pluginLayout and panels
formatMoneyfunction@luxalgo/vela-pro/pluginLayout and panels
formatPercentfunction@luxalgo/vela-pro/pluginLayout and panels
formatPricefunction@luxalgo/vela-pro/pluginLayout and panels
formatQtyfunction@luxalgo/vela-pro/pluginLayout and panels
groupLevelsfunction@luxalgo/vela-pro/pluginData feeds
hfunction@luxalgo/vela-pro/pluginLayout and panels
hasDepthFeedfunction@luxalgo/vela-pro/pluginData feeds
iconfunction@luxalgo/vela-pro/pluginLayout and panels
ProviderQuotesclass@luxalgo/vela-pro/pluginData feeds
Quoteinterface@luxalgo/vela-pro/pluginData feeds
QuoteSourceinterface@luxalgo/vela-pro/pluginData feeds
registerBottomPanelfunction@luxalgo/vela-pro/pluginLayout and panels
registerProIconsfunction@luxalgo/vela-pro/pluginLayout and panels
sideRailfunction@luxalgo/vela-pro/pluginLayout and panels
symbolPickerfunction@luxalgo/vela-pro/pluginSymbols
SymbolPickerLikeinterface@luxalgo/vela-pro/pluginSymbols
TapeTradeinterface@luxalgo/vela-pro/pluginData feeds
timeframeMsfunction@luxalgo/vela-pro/pluginReplay and strategy
withChangefunction@luxalgo/vela-pro/pluginData feeds

On this page