# Custom indicators (/vela-pro/indicators/custom-indicators)



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 [#choosing-a-format]

| Use case                                              | Recommended format       | Why                                                                                                                           |
| ----------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| User-authored or dynamically updated scripts          | Pine Script® source      | Requires no build step, can be modified at run time, and opens directly in the Pine code editor.                              |
| Default scripts preloaded onto new charts             | Workspace manifest entry | Configured once on `VelaWorkspace` and attached automatically to every new chart.                                             |
| Proprietary TypeScript logic or external service data | Native indicator         | Runs in your application bundle with direct access to services, and appears in the indicator menu alongside built-in studies. |
| Proprietary scripting language                        | Custom `ScriptingEngine` | See [Custom runtimes](/vela-pro/indicators/runtimes/engines).                                                                 |

## Pine Script® indicators [#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:

```js
//@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:

```ts
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](/vela-pro/indicators/pine/runtime) for engine options, library resolution, and error handling. The PineTS documentation lists all supported [`input.*` functions](/developers/pinets/api-coverage/input) and [plot functions](/developers/pinets/api-coverage/plots).

## Indicator manifest [#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:

```ts
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 },
    ],
});
```

| Property   | Default                  | Description                                                                                                                             |
| ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | required                 | Unique display and persistence key for the manifest entry. Keep this stable across releases so saved chart states continue matching it. |
| `script`   | `undefined`              | Inline script source string. Specify either `script` or `url`.                                                                          |
| `url`      | `undefined`              | Endpoint returning the script source text. Relative URLs resolve against the manifest URL when the manifest itself was loaded remotely. |
| `language` | Chart default (`'pine'`) | Language key of the scripting engine that executes the entry.                                                                           |
| `enabled`  | `true`                   | Whether 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](/vela-pro/indicators/library#using-the-default-core-picker).

## Native indicators [#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:

```ts
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 property                 | Description                                                                                                                                               |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                              | Unique type identifier. Namespace custom IDs (such as `acme.sma`) to avoid colliding with built-in types.                                                 |
| `title`, `shortTitle`               | Full name displayed in the indicator menu, and compact label displayed on the legend row and settings header.                                             |
| `paneHint`, `overlay`               | Use `'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.                                                                   |
| `multiInstance`                     | Set to `true` to allow multiple instances on the same chart; when omitted or `false`, subsequent `addNativeIndicator` calls return the existing instance. |
| `waitsForHistory`                   | Set to `true` to defer initial execution until historical backfill completes, useful for recursive or cumulative indicators.                              |
| `reactsToViewport`                  | Set 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](/vela/contributing/plugin-sdk#native-indicators--registernativeindicator).

## Display and user controls [#display-and-user-controls]

### Panes and legend rows [#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](/vela-pro/indicators/runtimes/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 [#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 [#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](/vela-pro/indicators/runtimes/charting-adapters#custom-renderer-layers) for a complete implementation and the core [plugin SDK](/vela/contributing/plugin-sdk#renderer-layers--registerrendererlayer) 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).

## Related [#related]

* [Built-in indicators](/vela-pro/indicators/included)
* [Charting adapters](/vela-pro/indicators/runtimes/charting-adapters)
* [Indicator persistence](/vela-pro/persistence/stores/indicators)
