Overview
Configure built-in and Vela Pro chart types, switch chart styles programmatically, handle data capability requirements, and register custom chart types.
A chart type controls how a chart renders its primary price series. Vela's open-source core includes nine built-in chart types, Vela Pro adds Footprint and TPO, and host applications can register additional custom types through the plugin SDK.
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',
timeframe: '60',
priceStyle: 'heikinashi', // initial chart type
live: true,
providers: { binance: () => new BinanceProvider() },
});
workspace.active.setPriceStyle('tpo'); // switch at runtime without reloadingIn the workspace and chart APIs, chart types are addressed as price styles via the priceStyle constructor option and the setPriceStyle() method using the string IDs below.
Built-in chart types
| ID | Menu label | Description |
|---|---|---|
candles | Candles | Standard OHLC candlesticks (default) |
bars | Bars | OHLC vertical bars with open and close ticks |
line | Line | Continuous line connecting bar close prices |
linemarkers | Line with markers | Close line with circular markers on each bar when horizontal spacing permits |
stepline | Step line | Horizontal step line holding each close flat until the next bar |
area | Area | Close line with a shaded gradient fill underneath |
baseline | Baseline | Close line split across a configurable reference price and colored above and below |
columns | Columns | Vertical histogram columns drawn from the bottom of the pane to each bar's close |
heikinashi | Heikin Ashi | Smoothed Heikin Ashi candlesticks; active indicators also compute on the smoothed bars |
Hollow candles are configured as a style setting on candles rather than a separate chart type. See Hollow candles in the core documentation.
Vela Pro chart types
| ID | Menu label | Description | Required data |
|---|---|---|---|
footprint | Footprint | Traded buy and sell volume at each price level per bar, rendered beside or inside candles | OHLCV candles plus a provider implementing FootprintFeed |
tpo | TPO | Per-session Time Price Opportunity (market profile) lettered blocks overlaid on candles | OHLC candles |
enableVelaPro() registers both types by default. Pass footprint: false or tpo: false to disable either type, or call enableFootprint() and enableTpo() individually when enabling features selectively. For full configuration details, see Footprint and TPO.
Both IDs are plain string literals ('footprint' and 'tpo'). Always call enableVelaPro() (or the standalone enablers) before creating a workspace or chart, because charts mount registered renderer layers during construction and fall back to 'candles' when given an unregistered priceStyle ID.
Switching chart types in the UI
Clicking the Chart style button in the topbar opens a dropdown menu listing the nine built-in types first, followed by a divider and any types registered by Vela Pro or your application. The same selector appears in the Chart settings dialog under the Symbol tab (Type row), and on mobile viewports under the Chart type row of the overflow menu.
Switching chart types updates the chart in place while keeping all indicators and drawings intact. Each cell's selected chart type is saved in the workspace state document.
Programmatic control
In a multi-chart workspace, each cell maintains an independent chart type:
import type { VelaWorkspace } from '@luxalgo/vela/workspace';
declare const workspace: VelaWorkspace;
workspace.active.setPriceStyle('footprint'); // active chart cell
workspace.cell('eth')?.setPriceStyle('line'); // specific grid cell by ID
workspace.on('cell:priceStyle', ({ id, from, to }) => {
console.log(`chart ${id} switched from ${from} to ${to}`);
});workspace.active.priceStyle returns the chart type currently rendered by the active cell. The cell:priceStyle event fires before the chart repaints whenever a user or script changes the chart type. Avoid calling setPriceStyle() synchronously inside a cell:priceStyle listener.
When working with a standalone Vela chart instance outside a workspace, call chart.renderer.set('priceStyle', id).
Data requirements and fallback behavior
Not every symbol supports every chart type. For example, a single-value economic index series has no open, high, or low prices, so candlestick and bar types cannot render it. Data providers advertise series capabilities through symbol metadata (ohlc: false, volume: false), and each chart type declares what fields it requires:
| Chart type | Required fields |
|---|---|
candles, bars, heikinashi | Open, high, and low |
tpo | Open, high, and low |
footprint | Open, high, low, and volume |
| All other built-in types | Close only |
When the active symbol omits a required field, unsupported chart types appear disabled in the menu with the tooltip "Not available for this symbol's data". If the chart was already set to an unsupported type, it temporarily falls back to 'linemarkers' while preserving the user's requestedPriceStyle so the preferred type restores automatically when switching to a compatible symbol. Before symbol metadata finishes loading, all chart types remain selectable.
import type { VelaWorkspace } from '@luxalgo/vela/workspace';
declare const workspace: VelaWorkspace;
const cell = workspace.active;
cell.requestedPriceStyle; // 'footprint' (the user's selected style)
cell.priceStyle; // 'linemarkers' (active fallback while unsupported)
cell.unavailablePriceStyles(); // disabled style IDs for custom UI pickersMenu availability for Footprint only checks whether the symbol provides OHLC and volume metadata. Rendering footprint cells also requires a provider that implements FootprintFeed. See Footprint for fallback behavior on candle-only providers.
See Custom data providers to configure symbol capability metadata in your provider.
Registering custom chart types
Custom chart types compose three primitives from @luxalgo/vela/plugin (the same SDK interfaces used by Footprint and TPO):
registerChartTypeadds the style ID and label to chart style menus, declares data capability checks, and attaches an optional data engine factory.- A
SeriesDataEngineruns per chart instance to compute or fetch supplemental data beyond standard candles and push it to the renderer viahost.pushData(). registerRendererLayermounts a dedicated<canvas>overlay. A renderer layer registered with the sameidas the chart type receives whatever payloadpushData()emits.
The example below registers a 'midline' chart type that connects the midpoint of each bar's high-low range. First, register the chart type and its data engine:
import { registerChartType, type SeriesDataEngineHost } from '@luxalgo/vela/plugin';
registerChartType({
id: 'midline',
label: 'Midline',
supports: (facts) => facts.ohlc !== false,
dataEngine: () => {
let host: SeriesDataEngineHost | null = null;
// Emit one midpoint coordinate per bar to the matching renderer layer.
const push = (): void => {
host?.pushData(host.bars().map((bar) => ({ time: bar.time, price: (bar.high + bar.low) / 2 })));
};
return {
start(next) {
host = next;
push();
},
suspend() {},
resume: push,
stop() {
host = null;
},
onBars: push,
};
},
});Next, register the matching renderer layer, which draws only when 'midline' is the active priceStyle:
import { registerRendererLayer } from '@luxalgo/vela/plugin';
registerRendererLayer({
id: 'midline',
create: () => {
let canvas: HTMLCanvasElement | null = null;
return {
mount(el) {
canvas = el;
},
render({ data, coords, scale, bounds, priceStyle, theme }) {
const ctx = canvas?.getContext('2d');
if (!canvas || !ctx) return;
ctx.setTransform(coords.dpr, 0, 0, coords.dpr, 0, 0);
ctx.clearRect(0, 0, canvas.width, canvas.height);
if (priceStyle !== 'midline' || !Array.isArray(data)) return;
ctx.beginPath();
for (const point of data as { time: number; price: number }[]) {
ctx.lineTo(coords.timeToX(point.time), coords.priceToY(point.price, scale, bounds));
}
ctx.strokeStyle = theme.textColor;
ctx.stroke();
},
};
},
});By default, standard candlesticks continue painting beneath your custom layer. Set basePainting: 'none' on registerChartType when your layer replaces the base price series entirely. Data engines that fetch external series can reach custom methods on the active provider instance through host.data.providerInstance(name).
For complete lifecycle details, bar transforms, and custom settings tabs, see Chart types, Renderer layers, and Settings rows in the core documentation.