# Standalone widgets (/vela-pro/modules/widgets)



Every Vela Pro module panel is built as a standalone widget factory that returns a DOM element and lifecycle methods. You can mount a watchlist in a custom terminal column, embed an order ticket inside an application modal, or render a market calendar on a page with no chart at all. Inside a `VelaWorkspace`, modules mount these same widgets into workspace panels.

```ts
import { DARK_THEME } from '@luxalgo/vela';
import { ensureUIHost } from '@luxalgo/vela/ui';
import { createCalendar, type CalendarSource } from '@luxalgo/vela-pro-calendar';

declare const source: CalendarSource;

const box = document.getElementById('calendar')!;
ensureUIHost(box, DARK_THEME);

const calendar = createCalendar({
    source,
    host: box,
    onSelectSymbol: (symbol) => window.location.assign(`/chart/${encodeURIComponent(symbol)}`),
});
box.append(calendar.el);
```

Standalone widgets do not require a chart instance or a call to `enableVelaPro()`. Each widget receives all required state and callbacks through its props.

## Available widgets [#available-widgets]

| Factory                      | Package                       | UI surface                                           | `tools` header controls                  |
| ---------------------------- | ----------------------------- | ---------------------------------------------------- | ---------------------------------------- |
| `createWatchlist(props)`     | `@luxalgo/vela-pro-watchlist` | Symbol lists, live quotes, and symbol details        | List selector, Add symbol, settings      |
| `createWatchlistView(props)` | `@luxalgo/vela-pro-watchlist` | Full-width watchlist analytics view                  | None                                     |
| `createOrderBook(props)`     | `@luxalgo/vela-pro-dom`       | Depth book, DOM ladder, and trades tape              | Venue selector, price grouping, settings |
| `createAlertsList(props)`    | `@luxalgo/vela-pro-alerts`    | Alert rules and firing history log                   | None                                     |
| `createOrderTicket(props)`   | `@luxalgo/vela-pro-trading`   | Interactive order entry ticket                       | None                                     |
| `createTradingPanel(props)`  | `@luxalgo/vela-pro-trading`   | Positions, working orders, order history, and trades | None                                     |
| `createJournalPanel(props)`  | `@luxalgo/vela-pro-journal`   | Compact trading journal summary                      | Account selector, Add trade, Maximize    |
| `createJournalView(props)`   | `@luxalgo/vela-pro-journal`   | Full-screen trading journal dashboard                | None                                     |
| `createCalendar(props)`      | `@luxalgo/vela-pro-calendar`  | Economic releases, corporate events, and holidays    | Impact filter, refresh                   |

See each module's widget reference for its full props table: [Watchlist](/vela-pro/modules/catalog/watchlist#widgets), [Alerts](/vela-pro/modules/catalog/alerts#widgets), [Order book](/vela-pro/modules/catalog/order-book#widgets), [Trading](/vela-pro/modules/trading/overview#widgets), [Journal](/vela-pro/modules/catalog/journal#widgets), and [Calendar](/vela-pro/modules/catalog/calendar#widgets).

## Widget interface [#widget-interface]

| Member          | Description                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `el`            | Root `HTMLElement` to mount in the DOM. Widgets fill their parent box, so mount `el` inside an explicitly sized container or a CSS Grid/Flexbox cell.   |
| `tools`         | Optional `HTMLElement` containing compact header controls. Renders in the widget's top bar by default, or can be reparented into your own panel header. |
| `update(props)` | Updates mutable props after creation, such as `symbol`, `active`, or event callbacks.                                                                   |
| `destroy()`     | Removes `el` from the DOM and tears down widget-owned subscriptions.                                                                                    |

All Vela Pro widgets follow four lifecycle conventions:

* **Props in, callbacks out:** Widgets never read from a chart directly. State enters through props (such as a `controller`, data source, and `symbol`) and user interactions leave through callbacks (`onSelectSymbol`, `onOpenAlert`, `onMaximize`, `onShowTrade`, `onNotify`).
* **Callback-driven controls:** Optional UI buttons render only when their corresponding callback is supplied. Without `onMaximize`, the watchlist and journal panels hide Maximize; without `onClose`, the trading panel hides Close.
* **Visibility gating (`active`):** Calling `update({ active: false })` pauses live quote and depth subscriptions on the watchlist and order book until `active` returns to `true`, and clears any staged draft on the order ticket.
* **Explicit teardown (`destroy()`):** `destroy()` unmounts the widget and closes its internal streams. Controllers and shared quote sources remain owned by host code; call `trading.destroy()` and `quotes.dispose()` when tearing down the page.

## Host setup [#host-setup]

Inside a `VelaWorkspace`, modules wire themes, controllers, and price feeds automatically. On a custom page, your host code provides that plumbing:

| Provided by `VelaWorkspace`                 | Host setup on a custom page                                                                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Theme variables and overlay portal layer    | Call `ensureUIHost(element, theme)` once on a container and pass that element as each widget's `host` (see [Theming](/vela/ui/theming)).                         |
| Shared module controllers                   | Instantiate one controller per module (`WatchlistController`, `AlertsController`, `TradingController`, `JournalController`, `CalendarController`) with its port. |
| Live quotes                                 | Pass a `QuoteSource`, such as `new ProviderQuotes(() => chart.data)` over chart providers or a custom implementation.                                            |
| Symbol metadata, logos, and depth feeds     | Pass `directory` or `icons` as an accessor returning chart data (`() => chart.data`).                                                                            |
| Active symbol updates                       | Call `widget.update({ symbol })` on each widget whenever the selected symbol changes.                                                                            |
| Live price ticks for paper fills and alerts | Call `trading.notePrice(symbol, price, time)` and `alerts.notePrice(symbol, price, barTime)` on incoming ticks.                                                  |
| Broker-to-journal synchronization           | Call `journal.syncBroker(trading.broker)` once at startup.                                                                                                       |

Widgets bound to the same controller instance share live state automatically. Passing a single `TradingController` to `createOrderTicket`, `createTradingPanel`, and `createOrderBook` keeps orders and positions synchronized across all three surfaces. Instantiate at most one controller per module per page, because two `TradingController` instances pointing at the same persisted paper storage key will overwrite each other.

If your page also calls `enableVelaPro()`, reuse the controllers already created by the installed modules (`tradingController()`, `watchlistController()`, `alertsController()`, `journalController()`, and `calendarController()`) rather than constructing duplicates. To mount custom or built-in widgets as panels inside `VelaWorkspace` itself, see [Custom panels and widgets](/vela-pro/modules/extending/custom-widgets).

## Full example [#full-example]

The example below arranges a watchlist, a `VelaWorkspace` chart, an order book, and an order ticket in a custom CSS Grid layout, sharing market data and paper trading state across all surfaces.

```html
<div id="terminal">
    <div id="watchlist"></div>
    <div id="chart"></div>
    <div id="book"></div>
    <div id="ticket"></div>
</div>
```

```css
#terminal {
    display: grid;
    grid-template: 1fr 1fr / 320px 1fr 340px;
    height: 100vh;
}
#terminal > * { min-width: 0; min-height: 0; overflow: hidden; }
#watchlist, #chart { grid-row: 1 / 3; }
```

```ts
import { DARK_THEME, type DataProvider } from '@luxalgo/vela';
import { ensureUIHost } from '@luxalgo/vela/ui';
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import type { DepthFeed } from '@luxalgo/vela-pro';
import { ProviderQuotes, onActiveSymbol } from '@luxalgo/vela-pro/plugin';
import { createOrderBook } from '@luxalgo/vela-pro-dom';
import { PaperBroker, TradingController, createOrderTicket } from '@luxalgo/vela-pro-trading';
import { LocalWatchlistStorage, WatchlistController, createWatchlist } from '@luxalgo/vela-pro-watchlist';

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

const page = document.getElementById('terminal')!;
ensureUIHost(page, DARK_THEME);

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    live: true,
    providers: { acme: () => new MyProvider() },
});
const ctx = workspace.context();
const data = () => ctx.chart.data; // symbol metadata, logos, quotes, and depth streams

// Instantiate one controller per module.
const quotes = new ProviderQuotes(data);
const lists = new WatchlistController({ storage: new LocalWatchlistStorage() });
const trading = new TradingController({ broker: new PaperBroker() });

const openSymbol = (symbol: string): void => ctx.setSymbol(symbol);
const watchlist = createWatchlist({ controller: lists, quotes, directory: data, host: page, onSelectSymbol: openSymbol });
const book = createOrderBook({ directory: data, host: page, trading: () => trading });
const ticket = createOrderTicket({ controller: trading, host: page, active: true });
document.getElementById('watchlist')!.append(watchlist.el);
document.getElementById('book')!.append(book.el);
document.getElementById('ticket')!.append(ticket.el);

// Keep every widget synchronized with the active chart symbol and forward live ticks to the paper broker.
let offBar = (): void => {};
onActiveSymbol(ctx, (symbol, chart) => {
    for (const widget of [watchlist, book, ticket]) widget.update({ symbol });
    offBar();
    offBar = chart?.on('bar', (bar) => trading.notePrice(symbol, bar.close, bar.time)) ?? ((): void => {});
});
```

Key integration details in this setup:

* `ensureUIHost` applies UI kit theme tokens to `#terminal` and creates a portal layer for menus and dialogs so popovers inherit theme styling.
* `ProviderQuotes` and `onActiveSymbol` are imported from `@luxalgo/vela-pro/plugin`. `onActiveSymbol` fires immediately with the initial symbol and active chart, then re-fires whenever the active cell or symbol changes.
* Passing `trading: () => trading` connects DOM ladder click-trading, order cancellation, and position closing to the same `TradingController` used by the order ticket. Omit `trading` for a read-only order book.
* Forwarding `'bar'` updates into `trading.notePrice` marks open positions and triggers simulated `PaperBroker` fills.

## Synchronizing widgets [#synchronizing-widgets]

| Desired interaction                                  | Integration wiring                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Clicking a watchlist row or position loads the chart | `onSelectSymbol: (symbol) => ctx.setSymbol(symbol)`                                                                       |
| Widgets follow active chart symbol changes           | `onActiveSymbol(ctx, (symbol) => widget.update({ symbol }))`                                                              |
| DOM ladder places, cancels, and closes orders        | `createOrderBook({ trading: () => trading })`                                                                             |
| Paper orders fill and price alerts evaluate          | Call `notePrice(symbol, bar.close, bar.time)` on `TradingController` and `AlertsController` inside `chart.on('bar', ...)` |
| Journal records executions from the trading account  | `journal.syncBroker(trading.broker)`                                                                                      |
| Alerts list opens the alert editor dialog            | `onOpenAlert: (seed) => openAlertDialog(ctx, alerts, seed)`                                                               |
| Watchlist row context menu creates an alert          | Add a `rowActions` item whose `run(symbol)` calls `openAlertDialog(ctx, alerts, { symbol })`                              |
| Watchlist or journal expands to full-screen view     | Supply `onMaximize` and mount `createWatchlistView` or `createJournalView` in an overlay container                        |

`ctx` is the `WidgetContext` returned by `workspace.context()`, which is required when opening the built-in `openAlertDialog` editor.

## Related [#related]

* [Theming and branding](/vela-pro/customization/theme)
* [Mobile widgets](/vela-pro/customization/mobile/widgets)
* [Custom panels and widgets](/vela-pro/modules/extending/custom-widgets)
