# Overview (/vela-pro/charts/chart-types/overview)



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.

```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',
    timeframe: '60',
    priceStyle: 'heikinashi', // initial chart type
    live: true,
    providers: { binance: () => new BinanceProvider() },
});

workspace.active.setPriceStyle('tpo'); // switch at runtime without reloading
```

In 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 [#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](/vela/user/renderer-features#hollow-candles) in the core documentation.

## Vela Pro chart types [#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](/vela-pro/charts/chart-types/footprint) and [TPO](/vela-pro/charts/chart-types/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 [#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 [#programmatic-control]

In a multi-chart workspace, each cell maintains an independent chart type:

```ts
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 [#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.

```ts
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 pickers
```

<Note>
  Menu 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](/vela-pro/charts/chart-types/footprint#data-requirements) for fallback behavior on candle-only providers.
</Note>

See [Custom data providers](/vela-pro/data/custom-source) to configure symbol capability metadata in your provider.

## Registering custom chart types [#registering-custom-chart-types]

Custom chart types compose three primitives from `@luxalgo/vela/plugin` (the same SDK interfaces used by Footprint and TPO):

* `registerChartType` adds the style ID and label to chart style menus, declares data capability checks, and attaches an optional data engine factory.
* A `SeriesDataEngine` runs per chart instance to compute or fetch supplemental data beyond standard candles and push it to the renderer via `host.pushData()`.
* `registerRendererLayer` mounts a dedicated `<canvas>` overlay. A renderer layer registered with the same `id` as the chart type receives whatever payload `pushData()` 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:

```ts
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`:

```ts
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](/vela/contributing/plugin-sdk#chart-types--registercharttype), [Renderer layers](/vela/contributing/plugin-sdk#renderer-layers--registerrendererlayer), and [Settings rows](/vela/architecture/settings-rows) in the core documentation.

## Related [#related]

* [Footprint](/vela-pro/charts/chart-types/footprint)
* [TPO](/vela-pro/charts/chart-types/tpo)
* [Events and subscriptions](/vela-pro/charts/events)
