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

Charting adapters

Emit series, fills, and drawings through the visual output model, or render custom graphics with canvas layers and chart types.

View as Markdown

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

ProducerOutput typeDelivery 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 elementModel fieldNotes
Line, area, step line, histogram, columns, circles, or crossesseries entry with kind set to 'line', 'area', 'step', 'histogram', 'columns', 'circles', or 'cross', plus pointsEach 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 paneseries entry with kind set to 'candle' or 'bar', plus barsUseful for synthetic OHLC series such as Cumulative Volume Delta candles.
Per-bar shapes and text annotationsseries entry with kind: 'markers', plus markersEach marker specifies position ('aboveBar', 'belowBar', or 'inBar'), shape, color, and optional text.
Shaded band between two seriesfills entry referencing fromSeriesId and toSeriesIdSupports a uniform color, per-bar colors, or a vertical gradient.
Horizontal reference levelpriceLines entrySpecifies price along with optional color, line style, width, and label title.
Vertical time-range highlightbackgrounds entrySpecifies from and to timestamps in epoch milliseconds and a fill color.
Trend line or ray between two coordinateslines entryAnchored by bar index or timestamp (xloc), supporting extend modes and arrowheads.
Styled rectangle with optional labelboxes entrySupports fill color, border styling, and aligned interior text.
Callout bubble or point labellabels entryAnchored to an exact price or positioned above or below a bar.
Multi-point path or polygonpolylines entryStraight or curved segments, open or closed, with optional interior fill.
Shaded region between two line drawingslinefills entryReferences two lines IDs and a fill color.
Anchored HUD tabletables entryPositioned at a pane corner or edge, supporting styled cells and merged spans.
Main-series candle tintingbarColorsAvailable on IndicatorModel (scripting engines only).
Simulated strategy order fillstradesAvailable on IndicatorModel (scripting engines only); see Strategies.
Arbitrary pixel graphicsCustom renderer layerSee 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

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

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 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({}) 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. 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.

On this page