# Order book (/vela-pro/api/order-book)



This page documents `@luxalgo/vela-pro-dom`, the order book (DOM) module package, including the `orderBook()` plugin factory, `createOrderBook` standalone widget, and ladder display settings.

Import symbols on this page from `@luxalgo/vela-pro-dom`. Related guides: [Order book](/vela-pro/modules/catalog/order-book), [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth), [Standalone widgets](/vela-pro/modules/widgets).

## Functions [#functions]

### `createOrderBook` [#createorderbook]

The order book (book, DOM ladder, trades tape) as a widget: `{ el, tools, update, destroy }`.

```typescript
function createOrderBook(props?: OrderBookProps): OrderBookWidget
```

See also: [`OrderBookProps`](/vela-pro/api/order-book#orderbookprops), [`OrderBookWidget`](/vela-pro/api/order-book#orderbookwidget).

### `dom` [#dom]

The order book (book, DOM ladder, trades tape) as a Vela Pro plugin. With trading added, the ladder trades.

```typescript
function dom(opts?: EnableOrderBookOptions): VelaProPlugin<void>
```

See also: [`EnableOrderBookOptions`](/vela-pro/api/order-book#enableorderbookoptions), [`VelaProPlugin`](/vela-pro/api/module-sdk#velaproplugin).

### `enableOrderBook` [#enableorderbook]

Enable the ORDER BOOK side panel on every shell built afterwards. Call ONCE. Idempotent.

```typescript
function enableOrderBook(opts?: EnableOrderBookOptions): void
```

See also: [`EnableOrderBookOptions`](/vela-pro/api/order-book#enableorderbookoptions).

### `mergeBooks` [#mergebooks]

Several venues' books as one: the sizes summed at each price, on the coarsest tick among them.

```typescript
function mergeBooks(books: readonly BookSnapshot[]): BookSnapshot | null
```

See also: [`BookSnapshot`](/vela-pro/api/data-feeds#booksnapshot).

## Classes [#classes]

### `OrderBookWidget` [#orderbookwidget]

```typescript
class OrderBookWidget {
    constructor(props?: OrderBookProps);
    readonly el: HTMLElement;
    readonly tools: HTMLElement;
    update(next: Partial<Omit<OrderBookProps, 'views' | 'rows'>>): void;
    destroy(): void;
    settings(): OrderBookSettings;
    applySettings(s: OrderBookSettings): void;
}
```

| Member            | Type                                                               | Description                                                                                                                 |
| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `constructor`     | `(props?: OrderBookProps)`                                         |                                                                                                                             |
| `el`              | `HTMLElement`                                                      |                                                                                                                             |
| `tools`           | `HTMLElement`                                                      | The compact controls (venue, grouping, settings): in the widget's top row until a host lifts them into a header of its own. |
| `update()`        | `(next: Partial<Omit<OrderBookProps, 'views' \| 'rows'>>) => void` |                                                                                                                             |
| `destroy()`       | `() => void`                                                       |                                                                                                                             |
| `settings()`      | `() => OrderBookSettings`                                          | What the user set, for a host to keep.                                                                                      |
| `applySettings()` | `(s: OrderBookSettings) => void`                                   | Apply settings a host kept (a saved session's, or another order book's).                                                    |

See also: [`OrderBookProps`](/vela-pro/api/order-book#orderbookprops), [`OrderBookSettings`](/vela-pro/api/order-book#orderbooksettings).

## Interfaces and types [#interfaces-and-types]

### `DepthDirectory` [#depthdirectory]

Resolves a symbol to the provider that streams its book and trades: the chart's data, or any source with the same methods. With `ready`, a symbol is resolved only once it has settled; with `symbols`, the book can be read from the market's other listings too.

```typescript
type DepthDirectory = Pick<WidgetContext['chart']['data'], 'resolve' | 'providerInstance' | 'canonicalSymbol'> & Partial<Pick<WidgetContext['chart']['data'], 'ready' | 'symbols'>>;
```

From `@luxalgo/vela/plugin`: `WidgetContext`.

### `DomColumn` [#domcolumn]

A DOM column. Orders (your working orders and position) and P\&L (the position's, were it closed at the price) show only with trading.

```typescript
type DomColumn =
    | 'orders'
    | 'pnl'
    | 'sold'
    | 'bid'
    | 'price'
    | 'ask'
    | 'bought'
    | 'delta'
    | 'volume'
    | 'last';
```

### `EnableOrderBookOptions` [#enableorderbookoptions]

Options for [`enableOrderBook`](/vela-pro/api/order-book#enableorderbook).

```typescript
interface EnableOrderBookOptions {
    views?: readonly OrderBookView[];
    clickTrading?: boolean;
    width?: number;
    order?: number;
    settings?: OrderBookSettings;
}
```

| Member          | Type                       | Description                                                                                                    |
| --------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `views?`        | `readonly OrderBookView[]` | The views and their order (default Book, DOM, Trades).                                                         |
| `clickTrading?` | `boolean`                  | A click on the DOM ladder trades there when trading is enabled (default true).                                 |
| `width?`        | `number`                   |                                                                                                                |
| `order?`        | `number`                   | Place among the panel buttons (default 3).                                                                     |
| `settings?`     | `OrderBookSettings`        | Initial settings: the DOM's columns, the depth mode, the combined book (the user's changes persist over them). |

See also: [`OrderBookSettings`](/vela-pro/api/order-book#orderbooksettings), [`OrderBookView`](/vela-pro/api/order-book#orderbookview).

### `OrderBookProps` [#orderbookprops]

The order book's props. `views` and `rows` are read once; the others can change through `update`.

```typescript
interface OrderBookProps {
    symbol?: string;
    directory?: () => DepthDirectory | null;
    views?: readonly OrderBookView[];
    rows?: number;
    host?: HTMLElement;
    active?: boolean;
    trading?: () => TradingApi | null;
    settings?: OrderBookSettings;
    onSettingsChange?: (settings: OrderBookSettings) => void;
    onPriceMenu?: (e: MouseEvent, at: { symbol: string; price: number; text: string }, actions: readonly PriceActionDescriptor[]) => { destroy(): void } | null;
}
```

| Member              | Type                                                                                                  | Description                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `symbol?`           | `string`                                                                                              | The market to follow.                                                                                                                 |
| `directory?`        | `() => DepthDirectory \| null`                                                                        | Finds the provider streaming the symbol's book and trades. Without one, the book says it is unsupported.                              |
| `views?`            | `readonly OrderBookView[]`                                                                            | The views and their order (default Book, DOM, Trades).                                                                                |
| `rows?`             | `number`                                                                                              | Rows a side in the Book view (default 14).                                                                                            |
| `host?`             | `HTMLElement`                                                                                         | Where menus mount (default: the widget's own element).                                                                                |
| `active?`           | `boolean`                                                                                             | Follow the market (default true). Off, the feeds close.                                                                               |
| `trading?`          | `() => TradingApi \| null`                                                                            | The trading surface DOM clicks trade through (null: the ladder is read-only).                                                         |
| `settings?`         | `OrderBookSettings`                                                                                   | Settings to start from (a host's saved ones).                                                                                         |
| `onSettingsChange?` | `(settings: OrderBookSettings) => void`                                                               | Called after the user changes a setting, with them all.                                                                               |
| `onPriceMenu?`      | `(e: MouseEvent, at: { symbol: string; price: number; text: string }, …` (truncated; see declaration) | A right-click on a price: the host opens a menu with these actions and returns it, to be closed by the next one. Without it, no menu. |

See also: [`DepthDirectory`](/vela-pro/api/order-book#depthdirectory), [`OrderBookSettings`](/vela-pro/api/order-book#orderbooksettings), [`OrderBookView`](/vela-pro/api/order-book#orderbookview), [`PriceActionDescriptor`](/vela-pro/api/module-sdk#priceactiondescriptor), [`TradingApi`](/vela-pro/api/module-sdk#tradingapi).

### `OrderBookSettings` [#orderbooksettings]

The order book's settings a host keeps between sessions.

```typescript
interface OrderBookSettings {
    domColumns?: readonly DomColumn[];
    cumulative?: boolean;
    combined?: boolean;
}
```

| Member        | Type                   | Description                                              |
| ------------- | ---------------------- | -------------------------------------------------------- |
| `domColumns?` | `readonly DomColumn[]` | The DOM's columns, in order; Price is always among them. |
| `cumulative?` | `boolean`              | Depth bars show the running total.                       |
| `combined?`   | `boolean`              | Read every listing of the market as one book.            |

See also: [`DomColumn`](/vela-pro/api/order-book#domcolumn).

### `OrderBookView` [#orderbookview]

```typescript
type OrderBookView = 'book' | 'dom' | 'trades';
```

## Constants [#constants]

### `DEFAULT_DOM_COLUMNS` [#default_dom_columns]

```typescript
const DEFAULT_DOM_COLUMNS: readonly DomColumn[];
```

See also: [`DomColumn`](/vela-pro/api/order-book#domcolumn).

### `DOM_COLUMNS` [#dom_columns]

```typescript
const DOM_COLUMNS: readonly DomColumn[];
```

See also: [`DomColumn`](/vela-pro/api/order-book#domcolumn).

### `ORDERBOOK_PANEL_ID` [#orderbook_panel_id]

```typescript
const ORDERBOOK_PANEL_ID: 'vela-pro.orderbook';
```
