# Watchlist (/vela-pro/modules/catalog/watchlist)



The Watchlist module adds a side panel for tracking symbol lists with live quotes. It is enabled by default when you call `enableVelaPro()`, and clicking any symbol row opens that symbol in the active chart.

Key features include:

* Multiple named watchlists with collapsible section headers and drag-and-drop row reordering.
* Symbol rows showing the last price, daily change, optional volume, and a one-month closing-price sparkline, with sortable column headers and gainers or losers filters.
* A symbol details pane beneath the list displaying the active chart symbol's daily range, open, high, low, and volume.
* A right-click context menu on each row to open the symbol on the chart, insert a section above, copy the ticker, remove the symbol, or trigger custom row actions.
* An expanded view covering the chart column with a daily briefing, multi-period performance metrics, a correlation matrix, and a full symbols table.

## Configuration [#configuration]

```ts
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro({
    watchlist: {
        defaultSymbols: ['BTCUSDT', 'ETHUSDT', 'SOLUSDT'],
        rowActions: [
            {
                id: 'acme.research',
                label: 'Open research',
                run: (_ctx, symbol) => window.open(`/research/${encodeURIComponent(symbol)}`),
            },
        ],
        width: 360,
    },
});

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

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

### Options [#options]

| Option           | Default                               | Description                                                                                                                      |
| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `storage`        | `new LocalWatchlistStorage()`         | `WatchlistStorage` adapter for persisting lists. Defaults to `localStorage` under the key `velapro.watchlists`.                  |
| `quotes`         | `ProviderQuotes` over chart providers | `QuoteSource` adapter supplying live quotes and daily bars.                                                                      |
| `defaultSymbols` | Cross-asset starter list              | Initial symbols used when storage is empty. Pass `[]` to start with an empty list.                                               |
| `rowActions`     | None                                  | Custom entries appended to each symbol's right-click menu. Each item has `id`, `label`, optional `icon`, and `run(ctx, symbol)`. |
| `width`          | `400`                                 | Initial side panel width in pixels. Users can resize the panel between 240 and 820 pixels.                                       |
| `order`          | `0`                                   | Sort order among side rail panel buttons (`0` places Watchlist first).                                                           |

When `defaultSymbols` is omitted, Vela Pro builds the initial list from a curated set of crypto, equity, ETF, futures, and forex tickers filtered to symbols supported by your registered providers and grouped into sections. If your providers match none of those tickers, the list starts with the active chart's symbol. Pass `defaultSymbols` to specify an explicit starter list.

With the default `quotes` implementation, each row reads from your chart data provider. Daily historical bars supply the previous close and session statistics, while the provider's daily bar subscription updates the last price in real time. Providers without `subscribe` are polled every 15 seconds. Quote subscriptions remain active only while the Watchlist panel is open.

## Controller API [#controller-api]

`watchlistController()` returns the page's `WatchlistController` instance after `enableVelaPro()` installs the module, or `null` before initialization.

```ts
import { watchlistController, watchlistModel } from '@luxalgo/vela-pro-watchlist';

const lists = watchlistController();
if (lists) {
    if (!lists.has('SOLUSDT')) lists.add('SOLUSDT'); // append to the active list
    lists.remove('XRPUSDT');

    // Create and select a new watchlist.
    lists.update((state) =>
        watchlistModel.addList(state, 'Earnings week', [
            { kind: 'symbol', symbol: 'AAPL' },
            { kind: 'symbol', symbol: 'NVDA' },
        ]),
    );

    lists.onChange((state) => console.info(state.activeId, state.lists.length));
}
```

`add`, `remove`, and `has` operate on the currently selected list. Structural mutations go through `update(op)`, which applies a pure state transition `(state: WatchlistState) => WatchlistState`. The `watchlistModel` namespace exports built-in transitions including `addList`, `renameList`, `deleteList`, `selectList`, `addSection`, `updateSection`, `removeSection`, `addSymbol`, `removeSymbol`, and `moveEntry`. Call `state()` to read the current snapshot, and await `ready` to wait until initial storage loading completes.

## Storage port [#storage-port]

Implement `WatchlistStorage` to persist watchlists to your backend. Both `load()` and `save()` can return synchronously or return a `Promise`.

```typescript
interface WatchlistStorage {
    load(): WatchlistState | null | Promise<WatchlistState | null>;
    save(state: WatchlistState): void | Promise<void>;
}

interface WatchlistState {
    lists: Array<{ id: string; name: string; entries: WatchlistEntry[] }>;
    activeId: string;
    columns: Record<'price' | 'change' | 'changePercent' | 'volume', boolean>;
    sparklines: boolean;
    details: boolean;
}

type WatchlistEntry =
    | { kind: 'symbol'; symbol: string }
    | { kind: 'section'; id: string; title: string; collapsed?: boolean };
```

Return `null` from `load()` when the user has no saved watchlists yet so the module initializes the default list. `save(state)` is called with the full `WatchlistState` (including visible column toggles, sparklines, and the details pane preference) after every modification.

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';
import type { WatchlistState, WatchlistStorage } from '@luxalgo/vela-pro-watchlist';

let loaded = false;

const storage: WatchlistStorage = {
    async load() {
        const res = await fetch('/api/watchlists', { credentials: 'include' });
        if (!res.ok && res.status !== 404) throw new Error(`Watchlists: HTTP ${res.status}`);
        loaded = true;
        return res.status === 404 ? null : ((await res.json()) as WatchlistState);
    },
    async save(state) {
        if (!loaded) return;
        await fetch('/api/watchlists', {
            method: 'PUT',
            credentials: 'include',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify(state),
        });
    },
};

enableVelaPro({ watchlist: { storage } });
```

<Warning>
  If `load()` rejects, the module falls back to creating a fresh default list and invokes `save()` on the next user edit. Guarding `save()` with a `loaded` flag as shown above prevents a transient network failure on load from overwriting existing server data.
</Warning>

`LocalWatchlistStorage(key)` is the default browser implementation. `MemoryWatchlistStorage` stores state in memory for the current session only, which is useful for tests and stateless demos.

## Custom quote source [#custom-quote-source]

Implement `QuoteSource` when quotes come from a dedicated market-data stream rather than from the chart's `DataProvider`.

```typescript
interface QuoteSource {
    /** Subscribe to live quotes for a symbol. Returns an unsubscribe function. */
    watch(symbol: string, onQuote: (quote: Quote) => void): () => void;
    /** Optional: return up to `count` daily bars in chronological order (oldest first). */
    dailyBars?(symbol: string, count: number): Promise<readonly OHLCV[]>;
}
```

| `Quote` field                   | Type                 | Description                                                                         |
| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
| `symbol`                        | `string`             | Symbol string matching the watchlist entry                                          |
| `last`                          | `number \| null`     | Latest traded price                                                                 |
| `prevClose`                     | `number \| null`     | Previous session close used as the baseline for daily change                        |
| `open`, `high`, `low`, `volume` | `number \| null`     | Current session OHLCV statistics                                                    |
| `change`, `changePercent`       | `number \| null`     | Daily net change and percentage change                                              |
| `spark`                         | `number[]`           | Historical daily closes for the sparkline (oldest first)                            |
| `tick`                          | `number`             | Minimum price increment used to format displayed prices                             |
| `updated`                       | `number`             | Timestamp of the latest quote update in epoch milliseconds                          |
| `unresolved`                    | `boolean` (optional) | When `true`, indicates no provider serves the symbol and renders placeholder dashes |

`blankQuote(symbol)` creates an empty `Quote` template, and `withChange(quote)` derives `change` and `changePercent` from `last` and `prevClose`.

```ts
import { blankQuote, enableVelaPro, withChange, type Quote, type QuoteSource } from '@luxalgo/vela-pro';

interface QuoteMessage {
    last: number;
    prevClose: number;
    open: number;
    high: number;
    low: number;
    volume: number;
}

class ServerQuotes implements QuoteSource {
    watch(symbol: string, onQuote: (quote: Quote) => void): () => void {
        const stream = new EventSource(`/api/quotes/${encodeURIComponent(symbol)}`);
        stream.onmessage = (event) => {
            const message = JSON.parse(String(event.data)) as QuoteMessage;
            onQuote(withChange({ ...blankQuote(symbol), ...message, tick: 0.01, updated: Date.now() }));
        };
        return () => stream.close();
    }
}

enableVelaPro({ watchlist: { quotes: new ServerQuotes() } });
```

`watch` is called for each symbol in the active list using the exact string stored in the entry (such as `BTCUSDT` or `binance:BTCUSDT`). Its returned cleanup function runs when the panel closes or when the symbol is removed from the active list. Implement `dailyBars` if you enable the expanded view, since multi-period returns, drawdowns, and cross-asset correlations are computed from daily bars. See [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth) for quote handling across Vela Pro.

## Widgets [#widgets]

You can mount both Watchlist surfaces outside a workspace as standalone components (see [Standalone widgets](/vela-pro/modules/widgets)). Both factories read `controller` and `quotes` once at creation and accept updated values for the remaining props via `update(props)`.

`createWatchlist(props)` creates the compact panel widget. Its `tools` element contains the list selector, the Add symbol trigger, the settings menu, and the expand button.

| Prop             | Description                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `controller`     | Required. `WatchlistController` managing list state.                                                                                          |
| `quotes`         | Required. `QuoteSource` feeding row prices.                                                                                                   |
| `directory`      | Accessor returning chart data (`() => chart.data`) for symbol descriptions, logos, and search indexing. Without it, rows display raw tickers. |
| `symbol`         | Currently active symbol highlighted in the list and shown in the details pane.                                                                |
| `host`           | Portal container for menus and popovers. Defaults to the widget's root element.                                                               |
| `rowActions`     | Function returning custom right-click menu actions with `id`, `label`, optional `icon`, and `run(symbol)`.                                    |
| `picker`         | Function returning a symbol picker dialog for Add symbol. Defaults to an inline search input when omitted.                                    |
| `active`         | Controls visibility and quote subscriptions. When `false`, quote feeds are paused. Defaults to `true`.                                        |
| `onSelectSymbol` | Callback invoked when the user clicks a symbol row.                                                                                           |
| `onMaximize`     | Callback invoked when the user clicks the expand button. Omit to hide the expand button.                                                      |

`createWatchlistView(props)` creates the full-width expanded view. It accepts `controller`, `quotes` (implementing `dailyBars`), `directory`, `symbol`, `host`, and `picker`, along with `onSelectSymbol`, `onMinimize`, and `onClose`. The Add symbol, minimize, and close buttons render only when their corresponding props are provided.

## Keyboard shortcuts [#keyboard-shortcuts]

These shortcuts apply when the Watchlist panel has focus.

| Keys              | Action                                                                  |
| ----------------- | ----------------------------------------------------------------------- |
| Up, Down          | Select the previous or next symbol in the list and load it on the chart |
| Delete, Backspace | Remove the highlighted symbol from the active list                      |

In the expanded view's symbols table, Up, Down, Home, and End move focus between rows, Space toggles row selection, Enter opens the symbol on the chart, and X, Delete, or Backspace removes it. Pressing Escape clears the current selection or returns to the chart when nothing is selected.

## Related [#related]

* [Alerts](/vela-pro/modules/catalog/alerts)
* [Symbol search](/vela-pro/data/symbols/symbol-search)
* [API reference: Watchlist](/vela-pro/api/watchlist)
