# Order book (/vela-pro/modules/catalog/order-book)



The Order Book module adds a side panel displaying real-time market depth and recent executions for the active chart's symbol. It is enabled by default when you call `enableVelaPro()` and streams data from any `DataProvider` that implements the `DepthFeed` interface.

The panel includes three views:

| View   | Contents                                                                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Book   | Ask levels stacked above bid levels with horizontal depth bars, bid-ask spread, and buy/sell book imbalance.                                          |
| DOM    | A price-stepped depth-of-market ladder with configurable columns that users can toggle from the settings menu and reorder by dragging column headers. |
| Trades | Time-and-sales execution tape with one-minute buy/sell volume share and a pause toggle.                                                               |

The panel header also provides a venue selector to inspect depth on individual venues listing the same instrument (or merge them into a combined cross-venue book), and each price row offers a right-click menu to draw a horizontal line, copy the price, or run actions contributed by peer modules.

## Configuration [#configuration]

`BinanceProvider` in Vela's open-source core supplies OHLCV candles only, so the Order Book requires a custom `DataProvider` that also implements `DepthFeed`.

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

// Custom data provider implementing both OHLCV candles and DepthFeed streams.
declare const MyProvider: new () => DataProvider & DepthFeed;

enableVelaPro({
    orderBook: {
        views: ['dom', 'book', 'trades'],
        settings: {
            domColumns: ['orders', 'bid', 'price', 'ask', 'volume'],
            cumulative: false,
        },
    },
});

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    live: true,
    providers: { acme: () => new MyProvider() },
    persist: true,
});
```

Pass `enableVelaPro({ orderBook: false })` to disable the module.

### Options [#options]

| Option         | Default                     | Description                                                                                                                             |
| -------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `views`        | `['book', 'dom', 'trades']` | Enabled views and their tab order. The first entry is selected when the panel opens.                                                    |
| `clickTrading` | `true`                      | Allows placing and managing orders from the DOM ladder when the Trading module is installed. Pass `false` to keep the ladder read-only. |
| `settings`     | See below                   | Initial display preferences (`domColumns`, `cumulative`, and `combined`).                                                               |
| `width`        | `400`                       | Initial side panel width in pixels. Users can resize the panel between 260 and 520 pixels.                                              |
| `order`        | `3`                         | Sort order among side rail panel buttons.                                                                                               |

`settings` configures initial defaults for preferences exposed in the panel's settings menu:

| Setting      | Default                                                        | Description                                                                                                  |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `domColumns` | `['orders', 'sold', 'bid', 'price', 'ask', 'bought', 'delta']` | Ordered list of visible DOM columns. `'price'` is always retained.                                           |
| `cumulative` | `true`                                                         | Renders depth bars using cumulative volume from the best bid/ask instead of per-level size.                  |
| `combined`   | `false`                                                        | Aggregates every matching venue listing of the market into a single book bucketed to the coarsest tick size. |

When `persist: true` is set on `VelaWorkspace`, user changes to these preferences are stored in the workspace state document and take precedence over `settings` on reload.

The Order Book module does not expose a controller because it stores no domain records beyond these three UI settings. To open the panel programmatically, call `workspace.context().togglePanel('vela-pro.orderbook', true)`.

### DOM columns [#dom-columns]

| Column               | Displayed value at each price level                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `'orders'`           | Working orders and open position markers. Visible only when Trading is installed and an order or position exists.  |
| `'pnl'`              | Hypothetical profit or loss if the open position were closed at that price. Visible only while a position is open. |
| `'bid'`, `'ask'`     | Resting bid and ask liquidity at that price level.                                                                 |
| `'price'`            | Price level.                                                                                                       |
| `'sold'`, `'bought'` | Cumulative seller-initiated and buyer-initiated traded volume since session tracking started.                      |
| `'delta'`            | Net traded volume (`bought` minus `sold`).                                                                         |
| `'volume'`           | Total traded volume (`bought` plus `sold`).                                                                        |
| `'last'`             | Size of the most recent print at that price level.                                                                 |

## DepthFeed port [#depthfeed-port]

The Order Book resolves the `DataProvider` serving the active chart's symbol and checks whether it implements `DepthFeed`. `subscribeBook` streams order book snapshots and `subscribeTrades` streams recent prints. You can implement either method independently; views without a backing stream display an unsupported message.

```typescript
interface DepthFeed {
    subscribeBook?(ticker: string, onBook: (book: BookSnapshot) => void, opts?: { depth?: number; onError?: (reason: string) => void }): DepthSubscription;
    subscribeTrades?(ticker: string, onTrades: (trades: TapeTrade[], history?: boolean) => void, opts?: { onError?: (reason: string) => void }): DepthSubscription;
}
```

See [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth) for the full `BookSnapshot` and `TapeTrade` schemas and an example implementation.

Streams open when the panel becomes visible and close shortly after it hides. Error strings passed to `onError` map to distinct empty states in the UI:

| Panel state                               | Condition                                                                                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| "No order book" or "No trades feed"       | The symbol's provider omits `subscribeBook` or `subscribeTrades`, or calls `onError` with a reason containing `unsupported` or `unknown market`. |
| "Order book unavailable" (with Try again) | `onError` is called with a reason containing `unavailable`, `limit`, or `plan`.                                                                  |
| "The feed dropped" (with Reconnect)       | `onError` is called with any other error message.                                                                                                |

The venue selector lists alternate listings of the same underlying instrument and contract type (matching spot with spot and perpetuals with perpetuals) across registered providers that implement `DepthFeed`.

## Ladder trading [#ladder-trading]

When the [Trading](/vela-pro/modules/trading/overview) module is installed, the DOM ladder automatically enables interactive order entry and management through `TradingApi`:

* **Click-to-trade:** Once unlocked in the panel header, clicking the bid column places a buy order at that price and clicking the ask column places a sell order. Click-to-trade automatically relocks whenever the panel opens or switches symbols, and remains disabled while viewing another venue's book because orders execute against the active chart's market.
* **Order chips:** Clicking an order chip in the `'orders'` column cancels that working order.
* **Position chip:** Clicking the position chip at the average entry price opens a menu to close the entire position, close half, or cancel working orders for that symbol.
* **Position footer:** A summary bar beneath the ladder displays current position size and unrealized PnL alongside Cancel all and Close buttons.

Ladder clicks honor all Trading safety settings, staging a draft in the order panel by default or submitting immediately when one-click trading is enabled. Pass `orderBook: { clickTrading: false }` to keep the DOM ladder read-only even when Trading is installed.

When the [Alerts](/vela-pro/modules/catalog/alerts) module is enabled, right-clicking a price row also includes an action to create a price alert at that level.

## Widgets [#widgets]

`createOrderBook(props)` mounts the Order Book as a standalone component outside a workspace (see [Standalone widgets](/vela-pro/modules/widgets)). All props are optional. `views` and `rows` are read once on creation, while the remaining props can be updated via `update(props)`.

| Prop               | Description                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbol`           | Market symbol to subscribe to.                                                                                                                                 |
| `directory`        | Accessor returning chart data (`() => chart.data`) used to locate the `DepthFeed` provider for `symbol`. Without it, the widget renders its unsupported state. |
| `views`            | Enabled views and their order. Defaults to `['book', 'dom', 'trades']`.                                                                                        |
| `rows`             | Number of price levels shown on each side of the Book view. Defaults to `14`.                                                                                  |
| `host`             | Portal container for menus. Defaults to the widget's root element.                                                                                             |
| `active`           | Controls stream lifecycle. When `false`, book and trade subscriptions close. Defaults to `true`.                                                               |
| `trading`          | Accessor returning a `TradingApi` (such as a `TradingController`) for DOM ladder execution, or `null` for a read-only ladder.                                  |
| `settings`         | Initial `domColumns`, `cumulative`, and `combined` preferences.                                                                                                |
| `onSettingsChange` | Callback invoked with the full settings object whenever the user updates a preference.                                                                         |
| `onPriceMenu`      | Callback invoked on price-row right-click with `(event, at, actions)` so host code can open a context menu. When omitted, right-clicking does nothing.         |

The widget's `tools` element contains the venue selector, price-step grouping control, and settings button. Use `settings()` and `applySettings(settings)` to persist user preferences across sessions when mounting outside a workspace.

## Related [#related]

* [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth)
* [Trading](/vela-pro/modules/trading/overview)
* [API reference: Order book](/vela-pro/api/order-book)
