# Footprint (/vela-pro/charts/chart-types/footprint)



The **Footprint** chart type renders traded volume at each price level inside every bar, split between buyer-initiated (ask) and seller-initiated (bid) volume. `enableVelaPro()` registers the chart type by default, and footprint cells render whenever the chart's data provider implements `FootprintFeed`.

```ts
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import type { DataProvider } from '@luxalgo/vela/plugin';
import { enableVelaPro, type FootprintFeed } from '@luxalgo/vela-pro';

// Custom provider implementing both the core DataProvider interface and FootprintFeed.
declare const MyProvider: new () => DataProvider & FootprintFeed;

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    timeframe: '15',
    priceStyle: 'footprint',
    live: true,
    providers: { mydata: () => new MyProvider() },
});
```

Setting `priceStyle: 'footprint'` initializes the chart directly in Footprint mode; without it, the chart starts on `'candles'` and users can switch from the **Chart style** menu. Call `enableFootprint()` before constructing the workspace if you want to register Footprint without enabling the rest of Vela Pro, or pass `enableVelaPro({ footprint: false })` to disable it.

The same visualization is also available as two overlay indicators for charts using candlesticks or another price style: **Footprint** (per-bar footprint) and **Visible Range Footprint** (edge profile strip). See [Built-in indicators](/vela-pro/indicators/included) for indicator usage.

## Data requirements [#data-requirements]

Standard OHLCV candles alone do not contain per-price volume breakdowns. Footprint reads 1-minute footprint slices containing buy and sell volume per price level, which the chart aggregates dynamically into the bars of any selected timeframe. Providers supply these slices by implementing `getFootprints`, `subscribeFootprints`, and `footprintCaps` alongside the `DataProvider` interface from Vela's open-source core. See [Footprint data](/vela-pro/data/feeds/footprints) for the full feed contract.

The **Chart style** menu enables Footprint on any symbol whose metadata includes OHLC and volume fields, regardless of provider. Selecting Footprint on a provider that does not implement `FootprintFeed` leaves standard candles on screen with no footprint cells or loading state, and logs a console warning naming the provider and symbol. If none of your providers serve footprint slices, pass `footprint: false` to `enableVelaPro()` to omit Footprint from the menu.

<Note>
  The sample providers bundled with the core (`BinanceProvider`, `CoinbaseProvider`, `HyperliquidProvider`) serve OHLCV candles only and do not implement `FootprintFeed`.
</Note>

## Display modes [#display-modes]

Each footprint renders price rows in one of five visual modes, while the **Cell values** (`displayValue`) setting controls the numbers printed inside each row (`Auto`, `Bid × Ask`, `Total`, `Delta`, `Trades`, or `Bid × Ask Trades`).

| Mode              | ID              | Row visualization                                                                   |
| ----------------- | --------------- | ----------------------------------------------------------------------------------- |
| Bid × Ask Profile | `bidAskProfile` | Horizontal sell bar extending left of a center axis and buy bar extending right     |
| Bid × Ask Ladder  | `bidAskLadder`  | Two side-by-side columns (sell on the left, buy on the right) shaded by volume      |
| Volume Profile    | `volume`        | Left-aligned total volume bar, either split into buy/sell segments or solid         |
| Delta Profile     | `delta`         | Net delta (buy minus sell) bar extending left when negative and right when positive |
| Absolute Delta    | `deltaAbs`      | Left-aligned bar sized by absolute delta magnitude and colored by delta sign        |

## Multiple footprints and visible range [#multiple-footprints-and-visible-range]

Each bar can display up to five per-bar footprints simultaneously. **Footprint 1** is always active, and users can enable **Footprint 2** through **Footprint 5** from the instance strip at the top of the Footprint settings tab. Each additional instance initializes with a distinct placement and mode:

| Instance    | Default position    | Default mode      |
| ----------- | ------------------- | ----------------- |
| Footprint 1 | Right of the candle | Bid × Ask Profile |
| Footprint 2 | Left                | Bid × Ask Ladder  |
| Footprint 3 | Within the candle   | Volume Profile    |
| Footprint 4 | Right               | Delta Profile     |
| Footprint 5 | Left                | Absolute Delta    |

Multiple footprints assigned to the same side share the horizontal gap between adjacent candles. At most one instance can sit `within` the candle body; setting a second instance to `within` moves it to the right of the candle.

In addition to per-bar footprints, the **visible-range profile** aggregates every bar currently in view into a single summary footprint strip docked along the right or left edge of the pane. It is enabled by default, configured under the **Visible range** section of the Footprint settings tab, and recalculates live as the user pans or zooms.

## Settings reference [#settings-reference]

When Footprint is the active chart type, the Chart settings dialog displays a **Footprint** tab next to **Symbol**. Every footprint instance exposes the following primary settings groups:

| Group               | Setting                              | Config key                                | Default                               |
| ------------------- | ------------------------------------ | ----------------------------------------- | ------------------------------------- |
| Display             | Mode                                 | `mode`                                    | Bid × Ask Profile (`'bidAskProfile'`) |
| Display             | Cell values                          | `displayValue`                            | Auto (`'auto'`)                       |
| Display             | Average trade size                   | `avgTradeSize`                            | Off (`false`)                         |
| Display             | Position                             | `position`                                | Right (`'right'`)                     |
| Display             | Row size, Ticks per row              | `rowMode`, `rowTicks`                     | Auto (`'auto'`), `4`                  |
| Display             | Hide candles                         | `hideCandles`                             | Off (`false`)                         |
| Display             | Shrink numbers to fit                | `textFit`                                 | Off (`false`)                         |
| Display             | Gradient cells                       | `gradient`                                | On (`true`)                           |
| VA & POC            | Value area, Value area (%)           | `valueArea`, `valueAreaPercent`           | On (`true`), `70`                     |
| VA & POC            | Point of control                     | `poc`                                     | On (`true`)                           |
| VA & POC            | Extend POC until broken              | `pocExtend`                               | Off (`false`)                         |
| Imbalances          | Imbalance highlight, Ratio (%)       | `imbalance`, `imbalanceRatio`             | Off (`false`), `300`                  |
| Imbalances          | Stacked imbalances, Min stacked rows | `imbalanceStacked`, `imbalanceStackCount` | Off (`false`), `3`                    |
| Unfinished auctions | Unfinished auctions                  | `unfinished`                              | Off (`false`)                         |
| Unfinished auctions | Extend until revisited               | `unfinishedExtend`                        | On (`true`)                           |
| Stat table          | Stat table, Position                 | `stats`, `statsPosition`                  | Off (`false`), Below (`'below'`)      |
| Filters             | Volume                               | `minVolume`, `maxVolume`                  | Off                                   |
| Filters             | Bid volume                           | `minBidVolume`, `maxBidVolume`            | Off                                   |
| Filters             | Ask volume                           | `minAskVolume`, `maxAskVolume`            | Off                                   |

Key analytical settings behave as follows:

* **Average trade size** (`avgTradeSize`): Recomputes each row as volume divided by trade count so cell values, the point of control, and imbalance comparisons reflect average print size. Requires a footprint feed that supplies trade counts.
* **Imbalance highlight** (`imbalance`, `imbalanceRatio`): Outlines any cell whose volume is at least `imbalanceRatio`% of the opposite side on the diagonal (ask compared against the bid one row lower; bid compared against the ask one row higher, so `300` requires 3× volume). **Stacked imbalances** (`imbalanceStacked`, `imbalanceStackCount`) fill a horizontal zone wherever three or more consecutive rows are imbalanced on the same side, extending rightward until price trades back into the zone.
* **Unfinished auctions** (`unfinished`, `unfinishedExtend`): Marks a bar's extreme high or low when both buyers and sellers printed at that price, optionally extending a horizontal ray until a subsequent bar revisits the level.
* **Stat table** (`stats`, `statsPosition`): Renders a per-bar summary strip displaying Total volume, Delta, and Delta % by default, with optional rows for Buy volume, Sell volume, volume percentages, and trade counts.

**Hide candles** (`hideCandles`) applies across the entire chart and therefore appears only under Footprint 1. Additional style rows configure colors, font sizes, and line widths.

## Programmatic configuration [#programmatic-configuration]

Footprint settings live under `chartTypes.footprint` in the chart renderer configuration. Pass a partial object to `renderer.applyConfig()` to update specific keys without resetting others:

```ts
import type { VelaWorkspace } from '@luxalgo/vela/workspace';

declare const workspace: VelaWorkspace;

const renderer = workspace.chart.renderer;

renderer.applyConfig({
    chartTypes: {
        footprint: {
            mode: 'delta',
            imbalance: true,
            imbalanceRatio: 400,
            fp2Enabled: true, // enable Footprint 2
            fp2Mode: 'volume',
            vrEnabled: false, // hide the visible-range profile
        },
    },
});

const config = renderer.getConfig() as { chartTypes?: Record<string, Record<string, unknown>> } | null;
const mode = config?.chartTypes?.footprint?.mode ?? 'bidAskProfile';

renderer.openSettings('Footprint'); // open Chart settings directly on the Footprint tab
```

Unprefixed keys configure **Footprint 1**. Prefix a capitalized key name with `fp2` through `fp5` for additional per-bar instances, or `vr` for the visible-range profile (for example, `fp3Position` or `vrMode`). Toggle `fp2Enabled` through `fp5Enabled` to add or remove per-bar footprints, and `vrEnabled` to show or hide the visible-range strip. Any omitted key uses its default value.

Enum settings accept string IDs rather than display labels:

| Key             | Accepted values                                                                   |
| --------------- | --------------------------------------------------------------------------------- |
| `mode`          | `'bidAskProfile'`, `'bidAskLadder'`, `'volume'`, `'delta'`, `'deltaAbs'`          |
| `displayValue`  | `'auto'`, `'bidAsk'`, `'volume'` (Total), `'delta'`, `'trades'`, `'bidAskTrades'` |
| `position`      | `'right'`, `'left'`, `'within'`                                                   |
| `rowMode`       | `'auto'`, `'manual'`                                                              |
| `statsPosition` | `'below'`, `'above'`                                                              |

Renderer configuration is included in serialized chart state, so Footprint settings persist automatically in workspace state documents. See [Layouts and chart state](/vela-pro/persistence/layouts).

## Context menu and hover inspection [#context-menu-and-hover-inspection]

Right-clicking directly on footprint cells opens a Footprint-specific context menu, while right-clicking elsewhere on the pane opens the standard chart menu:

| Menu item             | Action                                                          |
| --------------------- | --------------------------------------------------------------- |
| Stat table            | Toggles the per-bar stat table for Footprint 1                  |
| Average trade size    | Toggles Footprint 1 between total volume and average trade size |
| Visible range profile | Shows or hides the visible-range edge strip                     |
| Shrink numbers to fit | Scales Footprint 1 cell numbers down to fit narrower cells      |
| Hide Candles          | Hides base candlesticks underneath the footprints               |
| Footprint Settings    | Opens the Chart settings dialog on the Footprint tab            |

Hovering a footprint row opens a tooltip listing the row's price range, bid × ask, total volume, and delta. Holding `Shift` while hovering opens a magnified overlay of that bar and its immediate neighbors, sized wide enough to display every numeric label.

## Zoom behavior [#zoom-behavior]

Because footprint ladders require horizontal space per bar, the renderer crossfades smoothly between candlesticks and footprints as bar spacing changes:

* **Below 5 px per bar**: Only standard candlesticks render.
* **5 px to 10 px per bar**: Footprint cells fade in while candlestick bodies narrow to make room beside them (or fade out when a footprint is positioned `within` the candle).
* **10 px per bar and wider**: Footprints render at full opacity and background gridlines hide.

When **Hide candles** (`hideCandles`) is enabled, footprints remain visible at every zoom level because there are no base candles to crossfade into. The visible-range profile strip also stays visible regardless of zoom level.

When **Row size** is set to `Auto`, adjacent price ticks merge automatically as vertical space compresses so rows remain tall enough for text. Once cell numbers can no longer fit at a legible font size, all numbers in the footprint hide simultaneously while keeping the color-shaded cells visible.

Bars whose footprint slices are still in flight display pulsing skeleton rows. During [Bar replay](/vela-pro/charts/replay), Footprint never renders data past the newest revealed bar.

## Related [#related]

* [Footprint data](/vela-pro/data/feeds/footprints)
* [Chart types](/vela-pro/charts/chart-types/overview)
* [TPO](/vela-pro/charts/chart-types/tpo)
