# Charting adapters (/vela-pro/indicators/runtimes/charting-adapters)



Both scripting engines and native indicators render visuals on a chart by emitting declarative output objects defined by Vela's open-source core. The core handles pane assignment, canvas painting, legend values, and incremental diffing automatically. This page covers the standard visual model primitives alongside custom renderer layers and chart types for specialized graphics.

The function below builds a price channel with a shaded fill band that can be returned from either a native indicator's `ctx.emit()` call or a scripting engine's `IndicatorModel`:

```ts
import { ACCENT, stableSeriesId, type NativeIndicatorOutput, type OHLCV } from '@luxalgo/vela/plugin';

export function channelOutput(instanceId: string, bars: readonly OHLCV[], length: number): NativeIndicatorOutput {
    const upper = stableSeriesId({ instanceId, kind: 'line', title: 'Upper', ordinal: 0 });
    const lower = stableSeriesId({ instanceId, kind: 'line', title: 'Lower', ordinal: 0 });
    const style = { color: ACCENT, width: 1, lineStyle: 'solid' } as const;
    const extreme = (i: number, pick: (bar: OHLCV) => number, best: (a: number, b: number) => number): number | null => {
        if (i < length - 1) return null; // Emit null until the lookback window is full
        return bars.slice(i - length + 1, i + 1).map(pick).reduce((a, b) => best(a, b));
    };
    return {
        series: [
            { id: upper, title: 'Upper', paneId: '', kind: 'line', style, points: bars.map((bar, i) => ({ time: bar.time, value: extreme(i, (b) => b.high, Math.max) })) },
            { id: lower, title: 'Lower', paneId: '', kind: 'line', style, points: bars.map((bar, i) => ({ time: bar.time, value: extreme(i, (b) => b.low, Math.min) })) },
        ],
        fills: [{ id: stableSeriesId({ instanceId, kind: 'fill', title: 'Band', ordinal: 0 }), paneId: '', fromSeriesId: upper, toSeriesId: lower, color: 'rgba(41, 98, 255, 0.08)' }],
    };
}
```

Because the output describes data coordinates rather than pixel positions or DOM nodes, the same output renders in any pane, responds automatically to pan and zoom, and remains decoupled from renderer internals.

## Output interfaces [#output-interfaces]

| Producer                                                                                         | Output type                                                                                                         | Delivery method                                                          |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Scripting engine (Pine engine or [Custom runtimes](/vela-pro/indicators/runtimes/engines))       | `IndicatorModel` (visual primitives plus indicator `id`, `title`, `paneHint`, and `inputs`)                         | `handlers.onModel(model)` on the initial run and every subsequent update |
| Native indicator ([Custom indicators](/vela-pro/indicators/custom-indicators#native-indicators)) | `NativeIndicatorOutput` (visual primitives only; the core attaches `id`, `title`, and `inputs` from the descriptor) | `ctx.emit(output)`                                                       |

Both output interfaces and all supporting primitive types are exported from `@luxalgo/vela/plugin`.

## Model primitives [#model-primitives]

| Visual element                                                 | Model field                                                                                                                          | Notes                                                                                                                  |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Line, area, step line, histogram, columns, circles, or crosses | `series` entry with `kind` set to `'line'`, `'area'`, `'step'`, `'histogram'`, `'columns'`, `'circles'`, or `'cross'`, plus `points` | Each point is `{ time, value, color? }`. Set `value: null` for gaps; `color` overrides the color of an individual bar. |
| Derived OHLC candles or bars in an indicator pane              | `series` entry with `kind` set to `'candle'` or `'bar'`, plus `bars`                                                                 | Useful for synthetic OHLC series such as Cumulative Volume Delta candles.                                              |
| Per-bar shapes and text annotations                            | `series` entry with `kind: 'markers'`, plus `markers`                                                                                | Each marker specifies `position` (`'aboveBar'`, `'belowBar'`, or `'inBar'`), `shape`, `color`, and optional `text`.    |
| Shaded band between two series                                 | `fills` entry referencing `fromSeriesId` and `toSeriesId`                                                                            | Supports a uniform `color`, per-bar `colors`, or a vertical `gradient`.                                                |
| Horizontal reference level                                     | `priceLines` entry                                                                                                                   | Specifies `price` along with optional color, line style, width, and label title.                                       |
| Vertical time-range highlight                                  | `backgrounds` entry                                                                                                                  | Specifies `from` and `to` timestamps in epoch milliseconds and a fill `color`.                                         |
| Trend line or ray between two coordinates                      | `lines` entry                                                                                                                        | Anchored by bar index or timestamp (`xloc`), supporting `extend` modes and arrowheads.                                 |
| Styled rectangle with optional label                           | `boxes` entry                                                                                                                        | Supports fill color, border styling, and aligned interior text.                                                        |
| Callout bubble or point label                                  | `labels` entry                                                                                                                       | Anchored to an exact price or positioned above or below a bar.                                                         |
| Multi-point path or polygon                                    | `polylines` entry                                                                                                                    | Straight or curved segments, open or closed, with optional interior fill.                                              |
| Shaded region between two line drawings                        | `linefills` entry                                                                                                                    | References two `lines` IDs and a fill `color`.                                                                         |
| Anchored HUD table                                             | `tables` entry                                                                                                                       | Positioned at a pane corner or edge, supporting styled cells and merged spans.                                         |
| Main-series candle tinting                                     | `barColors`                                                                                                                          | Available on `IndicatorModel` (scripting engines only).                                                                |
| Simulated strategy order fills                                 | `trades`                                                                                                                             | Available on `IndicatorModel` (scripting engines only); see [Strategies](/vela-pro/indicators/backtesting/strategies). |
| Arbitrary pixel graphics                                       | Custom renderer layer                                                                                                                | See [Custom renderer layers](#custom-renderer-layers).                                                                 |

Four data rules apply across all model primitives:

* Timestamps are UTC epoch milliseconds matching the open time of the corresponding chart bar.
* Series `points` and `bars` are aligned to chart bars by array index, with one entry per evaluated bar in chronological order. Never omit array elements to skip bars, since doing so shifts subsequent points horizontally; emit `value: null` for gaps instead.
* Pass an empty string (`''`) for `paneId` so the core assigns the indicator's target pane automatically. To render a specific series or drawing on the price pane while keeping the rest of the indicator in a separate pane, set `overlay: true` on that element.
* Use a series' `display` flags to hide it selectively from the pane canvas, price scale, legend readout, or data window.

## Stable IDs [#stable-ids]

Every series, fill, and drawing carries a string `id` that tracks its identity across updates. Generate IDs deterministically using `stableSeriesId`:

```ts
import { stableSeriesId } from '@luxalgo/vela/plugin';

const id = stableSeriesId({ instanceId: 'acme.channel', kind: 'line', title: 'Upper', ordinal: 0 });
```

Pass the `instanceId` provided to `prepare()` (for scripting engines) or the descriptor `type` (for native indicators). `ordinal` disambiguates multiple outputs that share the same `kind` and `title`; count it from zero in a consistent order on every run.

Deterministic IDs are required for three reasons:

* **In-place updates**: On live ticks, the renderer matches incoming series to mounted plots by `id` and patches values without recreating GPU or canvas state. Unstable IDs force a full teardown and rebuild on every tick.
* **Cross-references**: Fill bands reference `fromSeriesId` and `toSeriesId` by ID, and legend readouts look up crosshair values by series ID.
* **Inspection stability**: Tools calling `chart.inspect()` rely on reproducible IDs across runs and page reloads.

Input definitions follow the same rule through their `key` property. Saved user preferences and programmatic `setInput()` calls address inputs by `key`, so keep input keys stable across indicator versions.

## Mounting and in-place updates [#mounting-and-in-place-updates]

Each emitted model flows through a four-step reconciliation pipeline:

1. **Pane routing**: The core routes overlay indicators to the price pane and creates a dedicated pane for non-overlay indicators, stamping the resolved `paneId` onto each element.
2. **Initial mount**: The renderer mounts series, drawings, the legend row, and the settings schema from the initial model.
3. **In-place value patching**: Subsequent emissions are diffed against the mounted model. When only data values or styles change (such as on a live tick, new bar, or numeric input change), the renderer updates existing primitives in place.
4. **Structural remount**: When the topology changes (for example, adding or removing a series, changing series `kind`, or switching panes), the indicator's visual presentation is rebuilt automatically.

Producers never choose manually between patching and remounting; always emit the full current model and let the core reconcile differences. During development or testing, call `chart.inspect()` to inspect the exact series, fills, and drawings currently mounted on the chart.

For deeper architectural background, see [Data flow](/vela/architecture/data-flow) and [Architecture overview](/vela/architecture/overview#the-neutral-model-the-lingua-franca) in the core documentation.

## Custom renderer layers [#custom-renderer-layers]

Visuals that cannot be represented as standard series or vector drawings (such as per-price heatmaps, session volume profiles, or multi-row bar tables) can paint directly onto a dedicated `<canvas>` element by pairing a native indicator with `registerRendererLayer`.

Registering a renderer layer with the same `id` as a native indicator's `type` binds the two together so payloads passed to `ctx.pushData(payload)` arrive as `data` inside the layer's `render()` callback. The example below draws a volume-intensity strip along the bottom edge of the price pane:

```ts
import { registerNativeIndicator, registerRendererLayer, type NativeIndicatorContext } from '@luxalgo/vela/plugin';

const TYPE = 'acme.volume-heat';

registerRendererLayer({
    id: TYPE,
    create: () => {
        let canvas: HTMLCanvasElement | null = null;
        return {
            mount: (element) => { canvas = element; },
            render: ({ data, coords, bounds }) => {
                const g = canvas?.getContext('2d');
                if (!canvas || !g) return;
                g.setTransform(coords.dpr, 0, 0, coords.dpr, 0, 0);
                g.clearRect(0, 0, canvas.width / coords.dpr, canvas.height / coords.dpr);
                const width = coords.bodySpacing();
                for (const cell of (data as Array<{ time: number; heat: number }> | null) ?? []) {
                    g.fillStyle = `rgba(255, 152, 0, ${cell.heat})`;
                    g.fillRect(coords.timeToX(cell.time) - width / 2, bounds.top + bounds.height - 6, width, 6);
                }
            },
        };
    },
});

registerNativeIndicator({
    type: TYPE,
    title: 'Volume heat',
    paneHint: 'price',
    overlay: true,
    inputsSchema: () => [],
    defaultInputs: () => ({}),
    create: () => {
        let ctx: NativeIndicatorContext | null = null;
        const push = (): void => {
            const bars = ctx?.bars() ?? [];
            const max = bars.reduce((most, bar) => Math.max(most, bar.volume ?? 0), 1);
            ctx?.pushData(bars.map((bar) => ({ time: bar.time, heat: (bar.volume ?? 0) / max })));
        };
        return {
            start: (context) => { ctx = context; ctx.emit({}); push(); },
            onBars: push,
            onViewport: () => {},
            setInputs: () => {},
            suspend: () => ctx?.pushData(null),
            resume: push,
            stop: () => { ctx?.pushData(null); ctx = null; },
        };
    },
});
```

Key implementation details for custom layers:

* Call `ctx.emit({})` in `start()` so the core mounts the indicator's legend row and settings dialog even when all visuals are painted on the custom layer.
* `payload` is opaque to the core and passed straight through to `render()`. Push `null` inside `suspend()` and `stop()` so hidden or removed instances clear their canvas.
* Apply `coords.dpr` scaling and clear the canvas at the start of every `render()` pass. Use `coords.timeToX(time)` or `coords.logicalToX(index)` for horizontal coordinates and `coords.priceToY(price, scale, bounds)` for vertical coordinates within the indicator's pane.
* The layer automatically follows its indicator when moved across panes or reordered. When `multiInstance: true` is set on the native indicator descriptor, each instance receives an isolated canvas element and data channel.
* Set `repaintOnCursor: true` on the layer descriptor and read `cursor` inside `render()` when painting hover highlights or custom tooltips.

If a custom-layer indicator occupies a dedicated pane with no numeric series, configure `paneAxis` in `ctx.emit()` to hide or relabel the vertical scale as shown in [Custom indicators](/vela-pro/indicators/custom-indicators#custom-canvas-rendering). Full coordinate and render arguments are documented in the core [plugin SDK](/vela/contributing/plugin-sdk#renderer-layers--registerrendererlayer).

## Custom chart types [#custom-chart-types]

Visualizations that replace or modulate the primary price series itself (such as footprint clusters or session TPO profiles) should be registered as chart types with `registerChartType` rather than as indicators. Registered chart types appear in the topbar chart-style selector and can attach a custom data engine that starts when the style is selected, queries extended provider methods via `host.data.providerInstance(name)`, and streams payloads to a matching renderer layer via `host.pushData(payload)`.

Vela Pro's Footprint and TPO chart types are built on this seam; see [Chart types](/vela-pro/charts/chart-types/overview) for details.

## Related [#related]

* [Custom indicators](/vela-pro/indicators/custom-indicators)
* [Custom runtimes](/vela-pro/indicators/runtimes/engines)
* [Plugin SDK](/vela/contributing/plugin-sdk) in the core documentation
