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

Custom indicators

Build custom indicators for Vela Pro using Pine Script®, workspace indicator manifests, or TypeScript native indicators.

View as Markdown

You can add custom indicators to a Vela Pro chart as a Pine Script® source string, an entry in the workspace indicators manifest, or a TypeScript native indicator registered with Vela's open-source core. This page covers all three formats alongside how their inputs, panes, and rendered outputs work on the chart.

Choosing a format

Use caseRecommended formatWhy
User-authored or dynamically updated scriptsPine Script® sourceRequires no build step, can be modified at run time, and opens directly in the Pine code editor.
Default scripts preloaded onto new chartsWorkspace manifest entryConfigured once on VelaWorkspace and attached automatically to every new chart.
Proprietary TypeScript logic or external service dataNative indicatorRuns in your application bundle with direct access to services, and appears in the indicator menu alongside built-in studies.
Proprietary scripting languageCustom ScriptingEngineSee Custom runtimes.

Pine Script® indicators

A Pine Script® indicator is a plain source string beginning with //@version=5 or //@version=6 and a single indicator() or strategy() declaration:

//@version=6
indicator("Acme Momentum")

length = input.int(14, "Length", minval=1)
mode   = input.string("RSI", "Mode", options=["RSI", "ROC"])

value = mode == "RSI" ? ta.rsi(close, length) : ta.roc(close, length)

plot(value, "Momentum", color=color.purple)
hline(50, "Middle")
plot(ta.ema(close, 20), "EMA 20", color=color.orange, force_overlay=true)

Three parts of the script control how it renders in the UI:

  • The indicator("Acme Momentum") declaration sets the legend title and opens a separate pane below the price chart by default. Pass overlay=true to draw on the price pane instead.
  • Each input.* call generates a field in the settings dialog (numeric inputs, options dropdowns, checkboxes, or color pickers), with group, inline, and tooltip controlling layout and help text. Each input's programmatic key matches the variable name assigned to it (length and mode above).
  • Plotting and drawing calls (plot, hline, fill, bgcolor, plotshape, line.new, label.new, box.new, and table.new) render in the indicator's assigned pane unless force_overlay=true routes an individual output onto the price pane.

Mount the script with chart.addIndicator(), passing initial input overrides by variable key:

import type { Vela } from '@luxalgo/vela';

declare const chart: Vela;
declare const acmeMomentum: string; // Source string above

const momentum = chart.addIndicator(acmeMomentum, { inputs: { length: 21, mode: 'ROC' } });
momentum.on('ready', () => console.log(momentum.inputs.map((input) => `${input.key}: ${input.type}`)));
momentum.setInput('length', 9);

See Pine Script® with PineTS for engine options, library resolution, and error handling. The PineTS documentation lists all supported input.* functions and plot functions.

Indicator manifest

The workspace indicators manifest defines the initial scripts attached when a workspace builds a new chart. Pass an array directly, a URL returning that JSON array, or an async loader function:

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    providers: { binance: () => new BinanceProvider() },
    indicators: [
        { name: 'Acme Momentum', url: '/scripts/acme-momentum.pine' },
        { name: 'EMA 20', script: '//@version=6\nindicator("EMA 20", overlay=true)\nplot(ta.ema(close, 20))' },
        { name: 'Acme Experimental', url: '/scripts/experimental.pine', enabled: false },
    ],
});
PropertyDefaultDescription
namerequiredUnique display and persistence key for the manifest entry. Keep this stable across releases so saved chart states continue matching it.
scriptundefinedInline script source string. Specify either script or url.
urlundefinedEndpoint returning the script source text. Relative URLs resolve against the manifest URL when the manifest itself was loaded remotely.
languageChart default ('pine')Language key of the scripting engine that executes the entry.
enabledtrueWhether the entry is mounted automatically on every newly created chart.
category'Indicators'Category heading used when displaying the entry in the default core indicator picker.

If an individual manifest script fails to load, the core logs a console warning and skips that entry so the rest of the chart initializes normally. However, if fetching the top-level manifest URL itself fails, initialization throws an error.

Because the Vela Pro indicator menu does not list workspace manifest entries, enabled: false is only useful when you restore the default core picker; see Indicator menu.

Native indicators

A native indicator consists of a static descriptor registered with registerNativeIndicator and a per-instance computation object that processes ctx.bars(). The example below registers a simple moving average:

import { ACCENT, registerNativeIndicator, stableSeriesId, type InputValue, type NativeIndicator, type NativeIndicatorContext } from '@luxalgo/vela/plugin';

const TYPE = 'acme.sma';

registerNativeIndicator({
    type: TYPE,
    title: 'Acme Moving Average',
    shortTitle: 'Acme MA',
    paneHint: 'price',
    overlay: true,
    multiInstance: true,
    waitsForHistory: true,
    inputsSchema: () => [{ key: 'length', title: 'Length', type: 'int', defval: 20, min: 1, max: 500 }],
    defaultInputs: () => ({ length: 20 }),
    create: (): NativeIndicator => {
        let ctx: NativeIndicatorContext | null = null;
        let length = 20;
        const read = (inputs: Record<string, InputValue>): void => {
            length = Math.max(1, Number(inputs.length ?? 20));
        };
        const compute = (): void => {
            if (!ctx) return;
            const bars = ctx.bars();
            let sum = 0;
            const points = bars.map((bar, i) => {
                sum += bar.close - (i >= length ? bars[i - length]!.close : 0);
                return { time: bar.time, value: i >= length - 1 ? sum / length : null };
            });
            const id = stableSeriesId({ instanceId: TYPE, kind: 'line', title: 'MA', ordinal: 0 });
            ctx.emit({ series: [{ id, title: 'MA', paneId: '', kind: 'line', points, style: { color: ACCENT, width: 2, lineStyle: 'solid' } }] });
        };
        return {
            start: (context, inputs) => { ctx = context; read(inputs); compute(); },
            onBars: compute,
            onViewport: () => {},
            setInputs: (inputs) => { read(inputs); compute(); },
            suspend: () => {},
            resume: compute,
            stop: () => { ctx = null; },
        };
    },
});

Call registerNativeIndicator() before constructing a workspace. Once registered, chart.addNativeIndicator('acme.sma', { inputs: { length: 50 } }) mounts an instance, and Vela Pro's indicator menu lists it automatically in the Basic tab.

Descriptor propertyDescription
typeUnique type identifier. Namespace custom IDs (such as acme.sma) to avoid colliding with built-in types.
title, shortTitleFull name displayed in the indicator menu, and compact label displayed on the legend row and settings header.
paneHint, overlayUse 'price' with overlay: true to draw on the price pane, or 'new' with overlay: false to open a separate pane.
inputsSchema(), defaultInputs()Input definitions rendered in the settings dialog and initial values for new instances.
multiInstanceSet to true to allow multiple instances on the same chart; when omitted or false, subsequent addNativeIndicator calls return the existing instance.
waitsForHistorySet to true to defer initial execution until historical backfill completes, useful for recursive or cumulative indicators.
reactsToViewportSet to true to receive onViewport callbacks during pan and zoom for visible-range calculations.
isSupported(symbol, data)Return false when the indicator cannot run on symbol, excluding it from the indicator menu for that market.
create()Factory returning a NativeIndicator instance with lifecycle hooks.

The core drives each NativeIndicator instance through seven lifecycle hooks: start (initial context and input values), onBars (real-time ticks, new bars, or historical backfill), onViewport (scroll or zoom updates), setInputs (user or API setting changes), suspend and resume (legend visibility toggles), and stop (disposal on removal). Pause any background timers or network subscriptions inside suspend.

Keep two output invariants in mind when implementing compute(). First, emit exactly one point per bar in ctx.bars() in chronological order, using value: null for missing values because the renderer aligns series points to chart bars by array index. Second, construct every series ID with stableSeriesId (passing TYPE as instanceId) so subsequent recalculations patch the series in place and preserve identity across reloads.

For the complete TypeScript signatures, see the core plugin SDK.

Display and user controls

Panes and legend rows

Both scripts and native indicators emit visuals using the same model primitives (series, fills, horizontal price lines, background spans, lines, labels, boxes, and tables), documented in Charting adapters.

The core places overlay indicators onto the price pane and opens a separate pane for non-overlay indicators. Users can move an indicator afterward with the Move to action on its legend row, and application code can call handle.moveTo('price') or handle.moveTo({ newPane: true }).

Each mounted instance renders a row in its pane's legend showing its short title and current plot values, along with visibility, settings, pane-move, and remove buttons. Vela Pro adds a favorites star to native and Pine Script® rows, plus an Edit code button on Pine Script® rows.

Scripts always allow multiple instances per chart, with each addIndicator() call creating an independent row and input state. Native indicators allow multiple instances only when multiInstance: true is set on the descriptor.

If a native indicator acts as an application-managed overlay (such as execution markers toggled from your custom toolbar), set legend: false on its descriptor to hide its legend row while controlling it via the IndicatorHandle returned by addNativeIndicator().

Inputs and settings dialog

The settings dialog is generated automatically from the indicator's input schema regardless of format. Every input definition specifies key, title, type, and defval. Supported input types are int, float, bool, string, color, source, price, time, session, timeframe, symbol, and text_area.

Providing an options array on a string input renders a select dropdown. Layout fields (group, inline, and tab) organize controls visually, while when conditionally displays an input based on another input's current value.

Changes in the dialog trigger a re-run for scripts or invoke setInputs() on native indicators. Programmatic updates via handle.setInput(key, value) and handle.setInputs(values) follow the same path, and the chart emits indicator:inputs on every change.

Custom canvas rendering

When standard plots and drawing primitives cannot express a visual (such as heatmaps, volume profiles, or pixel-sized grids), a native indicator can draw directly onto a dedicated <canvas> layer. Register a renderer layer with registerRendererLayer under the same id as the indicator's type, and stream arbitrary data to it via ctx.pushData(payload). The layer automatically tracks the indicator's target pane and z-order. See Charting adapters for a complete implementation and the core plugin SDK for layer lifecycle details.

When a dedicated pane contains only a custom canvas indicator with no numeric series, override its vertical scale by emitting paneAxis in ctx.emit(). Pass 'none' to hide axis labels, or pass { bands: [{ frac: 0.25, label: 'Volume' }] } to render categorical band labels at normalized vertical positions (the approach used by Vela Pro's Bar Stats indicator).

On this page