Charting adapters
Emit series, fills, and drawings through the visual output model, or render custom graphics with canvas layers and chart types.
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:
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
| Producer | Output type | Delivery method |
|---|---|---|
| Scripting engine (Pine engine or Custom runtimes) | 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) | 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
| 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. |
| Arbitrary pixel graphics | Custom renderer layer | See 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
pointsandbarsare 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; emitvalue: nullfor gaps instead. - Pass an empty string (
'') forpaneIdso 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, setoverlay: trueon that element. - Use a series'
displayflags to hide it selectively from the pane canvas, price scale, legend readout, or data window.
Stable IDs
Every series, fill, and drawing carries a string id that tracks its identity across updates. Generate IDs deterministically using stableSeriesId:
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
idand patches values without recreating GPU or canvas state. Unstable IDs force a full teardown and rebuild on every tick. - Cross-references: Fill bands reference
fromSeriesIdandtoSeriesIdby 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
Each emitted model flows through a four-step reconciliation pipeline:
- Pane routing: The core routes overlay indicators to the price pane and creates a dedicated pane for non-overlay indicators, stamping the resolved
paneIdonto each element. - Initial mount: The renderer mounts series, drawings, the legend row, and the settings schema from the initial model.
- 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.
- 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 and Architecture overview in the core documentation.
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:
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({})instart()so the core mounts the indicator's legend row and settings dialog even when all visuals are painted on the custom layer. payloadis opaque to the core and passed straight through torender(). Pushnullinsidesuspend()andstop()so hidden or removed instances clear their canvas.- Apply
coords.dprscaling and clear the canvas at the start of everyrender()pass. Usecoords.timeToX(time)orcoords.logicalToX(index)for horizontal coordinates andcoords.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: trueis set on the native indicator descriptor, each instance receives an isolated canvas element and data channel. - Set
repaintOnCursor: trueon the layer descriptor and readcursorinsiderender()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. Full coordinate and render arguments are documented in the core plugin SDK.
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 for details.
Related
- Custom indicators
- Custom runtimes
- Plugin SDK in the core documentation