# Watchlist (/vela-pro/api/watchlist)



This page documents `@luxalgo/vela-pro-watchlist`, including the `watchlist()` plugin factory, `WatchlistController`, standalone watchlist and symbol detail widgets, and the watchlist storage port.

Import symbols on this page from `@luxalgo/vela-pro-watchlist`. Related guides: [Watchlist](/vela-pro/modules/catalog/watchlist), [Standalone widgets](/vela-pro/modules/widgets).

## Functions [#functions]

### `createWatchlist` [#createwatchlist]

The watchlist as a widget: `{ el, tools, update, openAdd, destroy }`.

```typescript
function createWatchlist(props: WatchlistProps): WatchlistWidget
```

See also: [`WatchlistProps`](/vela-pro/api/watchlist#watchlistprops), [`WatchlistWidget`](/vela-pro/api/watchlist#watchlistwidget).

### `createWatchlistView` [#createwatchlistview]

The full view as a widget: `{ el, update, destroy }`.

```typescript
function createWatchlistView(props: WatchlistViewProps): WatchlistViewWidget
```

See also: [`WatchlistViewProps`](/vela-pro/api/watchlist#watchlistviewprops), [`WatchlistViewWidget`](/vela-pro/api/watchlist#watchlistviewwidget).

### `enableWatchlist` [#enablewatchlist]

Enable the WATCHLIST side panel on every shell built afterwards. Returns the page's [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class). Call ONCE, before constructing shells. Idempotent.

```typescript
function enableWatchlist(opts?: EnableWatchlistOptions): WatchlistController
```

See also: [`EnableWatchlistOptions`](/vela-pro/api/watchlist#enablewatchlistoptions), [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class).

### `watchlist` [#watchlist]

The watchlist as a Vela Pro plugin. With alerts on, a row's menu can create an alert.

```typescript
function watchlist(opts?: EnableWatchlistOptions): VelaProPlugin<WatchlistController>
```

See also: [`EnableWatchlistOptions`](/vela-pro/api/watchlist#enablewatchlistoptions), [`VelaProPlugin`](/vela-pro/api/module-sdk#velaproplugin), [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class).

### `watchlistController` [#watchlistcontroller]

```typescript
function watchlistController(): WatchlistController | null
```

See also: [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class).

### `watchlistLayout` [#watchlistlayout]

The row layout for a panel `width` px wide: Last, Chg and Chg% stay whatever the width and a narrower panel tightens the row instead; only Volume gives way when even the tightest row has no room for it.

```typescript
function watchlistLayout(
    chosen: Record<WatchlistColumnId, boolean>,
    width: number | null,
): WatchlistLayout

// Unexported supporting types referenced above
interface WatchlistLayout {
    density: WatchlistDensity;
    columns: Record<WatchlistColumnId, boolean>;
    widths: Record<WatchlistColumnId, number>;
}
type WatchlistDensity = 'roomy' | 'regular' | 'compact';
```

See also: [`WatchlistColumnId`](/vela-pro/api/watchlist#watchlistcolumnid).

## Classes [#classes]

### `LocalWatchlistStorage` [#localwatchliststorage]

```typescript
class LocalWatchlistStorage implements WatchlistStorage {
    constructor(key?: string);
    load(): WatchlistState | null;
    save(state: WatchlistState): void;
}
```

Default: `constructor(key = 'velapro.watchlists')`.

See also: [`WatchlistState`](/vela-pro/api/watchlist#watchliststate), [`WatchlistStorage`](/vela-pro/api/watchlist#watchliststorage).

### `MemoryWatchlistStorage` [#memorywatchliststorage]

```typescript
class MemoryWatchlistStorage implements WatchlistStorage {
    constructor(seed?: WatchlistState | null);
    load(): WatchlistState | null;
    save(state: WatchlistState): void;
}
```

Default: `constructor(seed = null)`.

See also: [`WatchlistState`](/vela-pro/api/watchlist#watchliststate), [`WatchlistStorage`](/vela-pro/api/watchlist#watchliststorage).

### `WatchlistController` class [#watchlistcontroller-class]

```typescript
class WatchlistController {
    constructor(opts: WatchlistControllerOptions);
    readonly ready: Promise<void>;
    state(): WatchlistState;
    onChange(cb: (s: WatchlistState) => void): () => void;
    update(op: (s: WatchlistState) => WatchlistState): void;
    seedIfEmpty(seed?: () => WatchlistEntry[]): Promise<boolean>;
    add(symbol: string): void;
    remove(symbol: string): void;
    has(symbol: string): boolean;
}
```

| Member          | Type                                                  | Description                                                                                                                                                            |
| --------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor`   | `(opts: WatchlistControllerOptions)`                  |                                                                                                                                                                        |
| `ready`         | `Promise<void>`                                       | Resolves once storage answered (an async backend).                                                                                                                     |
| `state()`       | `() => WatchlistState`                                |                                                                                                                                                                        |
| `onChange()`    | `(cb: (s: WatchlistState) => void) => () => void`     |                                                                                                                                                                        |
| `update()`      | `(op: (s: WatchlistState) => WatchlistState) => void` | Apply a pure operation from `./model` (or any state → state function).                                                                                                 |
| `seedIfEmpty()` | `(seed?: () => WatchlistEntry[]) => Promise<boolean>` | Fill an empty first list from the seed: after storage answered, so a kept state is never overwritten. Resolves false while the seed has nothing yet (ask again later). |
| `add()`         | `(symbol: string) => void`                            |                                                                                                                                                                        |
| `remove()`      | `(symbol: string) => void`                            |                                                                                                                                                                        |
| `has()`         | `(symbol: string) => boolean`                         |                                                                                                                                                                        |

See also: [`WatchlistControllerOptions`](/vela-pro/api/watchlist#watchlistcontrolleroptions), [`WatchlistEntry`](/vela-pro/api/watchlist#watchlistentry), [`WatchlistState`](/vela-pro/api/watchlist#watchliststate).

### `WatchlistViewWidget` [#watchlistviewwidget]

```typescript
class WatchlistViewWidget {
    constructor(props: WatchlistViewProps);
    readonly el: HTMLElement;
    update(next: Partial<Omit<WatchlistViewProps, 'controller' | 'quotes'>>): void;
    destroy(): void;
}
```

See also: [`WatchlistViewProps`](/vela-pro/api/watchlist#watchlistviewprops).

### `WatchlistWidget` [#watchlistwidget]

```typescript
class WatchlistWidget {
    constructor(props: WatchlistProps);
    readonly el: HTMLElement;
    readonly tools: HTMLElement;
    update(next: Partial<Omit<WatchlistProps, 'controller' | 'quotes'>>): void;
    openAdd(): void;
    destroy(): void;
}
```

| Member        | Type                                                                      | Description                                                                                                                    |
| ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `constructor` | `(props: WatchlistProps)`                                                 |                                                                                                                                |
| `el`          | `HTMLElement`                                                             |                                                                                                                                |
| `tools`       | `HTMLElement`                                                             | The compact controls (list switcher, add, settings): in the widget's top row until a host lifts them into a header of its own. |
| `update()`    | `(next: Partial<Omit<WatchlistProps, 'controller' \| 'quotes'>>) => void` |                                                                                                                                |
| `openAdd()`   | `() => void`                                                              | Open the add-symbol search.                                                                                                    |
| `destroy()`   | `() => void`                                                              |                                                                                                                                |

See also: [`WatchlistProps`](/vela-pro/api/watchlist#watchlistprops).

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

### `EnableWatchlistOptions` [#enablewatchlistoptions]

Options for [`enableWatchlist`](/vela-pro/api/watchlist#enablewatchlist).

```typescript
interface EnableWatchlistOptions {
    storage?: WatchlistStorage;
    quotes?: QuoteSource;
    defaultSymbols?: readonly string[];
    rowActions?: readonly WatchlistRowAction[];
    width?: number;
    order?: number;
}
```

| Member            | Type                            | Description                                                                                                                                                                           |
| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `storage?`        | `WatchlistStorage`              | Where watchlists are kept. Default: the browser's localStorage.                                                                                                                       |
| `quotes?`         | `QuoteSource`                   | Where quotes come from. Default: the chart's registered providers.                                                                                                                    |
| `defaultSymbols?` | `readonly string[]`             | The first list's symbols when nothing is kept yet (`[]` starts empty). Default: a cross-asset starter list (BTC, AAPL, SPY, ES, EURUSD…), kept to what the registered providers list. |
| `rowActions?`     | `readonly WatchlistRowAction[]` | Extra rows in a symbol's right-click menu.                                                                                                                                            |
| `width?`          | `number`                        |                                                                                                                                                                                       |
| `order?`          | `number`                        | Place among the panel buttons (default 0: first).                                                                                                                                     |

See also: [`QuoteSource`](/vela-pro/api/data-feeds#quotesource), [`WatchlistRowAction`](/vela-pro/api/watchlist#watchlistrowaction), [`WatchlistStorage`](/vela-pro/api/watchlist#watchliststorage).

### `SymbolDirectory` [#symboldirectory]

Names, logos and the search index: the chart's data, or any source with the same methods.

```typescript
type SymbolDirectory = Pick<WidgetContext['chart']['data'], 'ready' | 'canonicalSymbol' | 'resolve' | 'symbols' | 'displayPrefix' | 'symbolIcon'>;
```

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

### `Watchlist` interface [#watchlist-interface]

```typescript
interface Watchlist {
    id: string;
    name: string;
    entries: WatchlistEntry[];
}
```

See also: [`WatchlistEntry`](/vela-pro/api/watchlist#watchlistentry).

### `WatchlistAction` [#watchlistaction]

An extra row in a symbol's right-click menu (e.g. "Add alert…").

```typescript
interface WatchlistAction {
    id: string;
    label: string;
    icon?: string;
    run: (symbol: string) => void;
}
```

### `WatchlistColumnId` [#watchlistcolumnid]

```typescript
type WatchlistColumnId = 'price' | 'change' | 'changePercent' | 'volume';
```

### `WatchlistControllerOptions` [#watchlistcontrolleroptions]

```typescript
interface WatchlistControllerOptions {
    storage: WatchlistStorage;
    seed?: () => WatchlistEntry[];
}
```

| Member    | Type                     | Description                             |
| --------- | ------------------------ | --------------------------------------- |
| `storage` | `WatchlistStorage`       |                                         |
| `seed?`   | `() => WatchlistEntry[]` | The first list when storage holds none. |

See also: [`WatchlistEntry`](/vela-pro/api/watchlist#watchlistentry), [`WatchlistStorage`](/vela-pro/api/watchlist#watchliststorage).

### `WatchlistEntry` [#watchlistentry]

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

### `WatchlistProps` [#watchlistprops]

The watchlist's props. `controller` and `quotes` are read once; the others can change through `update`.

```typescript
interface WatchlistProps {
    controller: WatchlistController;
    quotes: QuoteSource;
    directory?: () => SymbolDirectory | null;
    symbol?: string;
    host?: HTMLElement;
    rowActions?: () => readonly WatchlistAction[];
    picker?: () => SymbolPickerLike | null;
    onSelectSymbol?: (symbol: string) => void;
    onMaximize?: () => void;
    active?: boolean;
}
```

| Member            | Type                               | Description                                                                                                                                                |
| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `controller`      | `WatchlistController`              | The lists and their symbols.                                                                                                                               |
| `quotes`          | `QuoteSource`                      | Live quotes for the rows.                                                                                                                                  |
| `directory?`      | `() => SymbolDirectory \| null`    | Names, logos and the search index. Without it, rows show their tickers.                                                                                    |
| `symbol?`         | `string`                           | The symbol in view elsewhere: its row is marked, its details shown underneath.                                                                             |
| `host?`           | `HTMLElement`                      | Where menus and popovers mount (default: the widget's own element).                                                                                        |
| `rowActions?`     | `() => readonly WatchlistAction[]` | Extra rows in a symbol's right-click menu.                                                                                                                 |
| `picker?`         | `() => SymbolPickerLike \| null`   | A symbol picker: "Add symbol" opens it in watchlist mode (else an inline search).                                                                          |
| `onSelectSymbol?` | `(symbol: string) => void`         | A row was opened.                                                                                                                                          |
| `onMaximize?`     | `() => void`                       | Open the advanced view ([`createWatchlistView`](/vela-pro/api/watchlist#createwatchlistview)). Its Maximize button shows only with it.                     |
| `active?`         | `boolean`                          | Shown or hidden (default shown). Hidden, it keeps no quote feed open (the last quotes stay on the rows); shown again, it resubscribes and measures itself. |

See also: [`QuoteSource`](/vela-pro/api/data-feeds#quotesource), [`SymbolDirectory`](/vela-pro/api/watchlist#symboldirectory), [`SymbolPickerLike`](/vela-pro/api/symbols#symbolpickerlike), [`WatchlistAction`](/vela-pro/api/watchlist#watchlistaction), [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class).

### `WatchlistRowAction` [#watchlistrowaction]

An extra row in a symbol's right-click menu of the sidebar's watchlist (e.g. "Add alert…").

```typescript
interface WatchlistRowAction {
    id: string;
    label: string;
    icon?: string;
    run: (ctx: WidgetContext, symbol: string) => void;
}
```

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

### `WatchlistState` [#watchliststate]

```typescript
interface WatchlistState {
    lists: Watchlist[];
    activeId: string;
    columns: Record<WatchlistColumnId, boolean>;
    sparklines: boolean;
    details: boolean;
}
```

| Member       | Type                                 | Description                                                         |
| ------------ | ------------------------------------ | ------------------------------------------------------------------- |
| `lists`      | `Watchlist[]`                        |                                                                     |
| `activeId`   | `string`                             |                                                                     |
| `columns`    | `Record<WatchlistColumnId, boolean>` | The columns the user chose (a narrow panel may hide Volume on top). |
| `sparklines` | `boolean`                            | Each row's 24h sparkline.                                           |
| `details`    | `boolean`                            | The details of the chart's symbol under the list.                   |

See also: [`Watchlist`](/vela-pro/api/watchlist#watchlist-interface), [`WatchlistColumnId`](/vela-pro/api/watchlist#watchlistcolumnid).

### `WatchlistStorage` [#watchliststorage]

Where watchlists are kept. `load` may answer null (nothing kept yet).

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

See also: [`WatchlistState`](/vela-pro/api/watchlist#watchliststate).

### `WatchlistViewProps` [#watchlistviewprops]

The full view's props. `controller` and `quotes` are read once; the others can change through `update`.

```typescript
interface WatchlistViewProps {
    controller: WatchlistController;
    quotes: QuoteSource;
    directory?: () => SymbolDirectory | null;
    symbol?: string;
    host?: HTMLElement;
    picker?: () => SymbolPickerLike | null;
    onSelectSymbol?: (symbol: string) => void;
    onMinimize?: () => void;
    onClose?: () => void;
}
```

| Member            | Type                             | Description                                                                                                          |
| ----------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `controller`      | `WatchlistController`            | The lists and their symbols.                                                                                         |
| `quotes`          | `QuoteSource`                    | Live quotes, and the daily bars the history-based sections read (`dailyBars`).                                       |
| `directory?`      | `() => SymbolDirectory \| null`  | Names, logos, asset types and the search index. Without it, symbols show their tickers.                              |
| `symbol?`         | `string`                         | The symbol in view on the chart.                                                                                     |
| `host?`           | `HTMLElement`                    | Where menus and tooltips mount. Default: the view's own element, which keeps them above it while it covers the page. |
| `picker?`         | `() => SymbolPickerLike \| null` | A symbol picker: Add symbol opens it in watchlist mode. The button shows only with it.                               |
| `onSelectSymbol?` | `(symbol: string) => void`       | A symbol was chosen (a row, Enter, Open on chart); the view then returns to the chart.                               |
| `onMinimize?`     | `() => void`                     | Back to the chart, the docked watchlist beside it. The button shows only with it.                                    |
| `onClose?`        | `() => void`                     | Close the watchlist altogether. The button shows only with it.                                                       |

See also: [`QuoteSource`](/vela-pro/api/data-feeds#quotesource), [`SymbolDirectory`](/vela-pro/api/watchlist#symboldirectory), [`SymbolPickerLike`](/vela-pro/api/symbols#symbolpickerlike), [`WatchlistController`](/vela-pro/api/watchlist#watchlistcontroller-class).

## Constants [#constants]

### `WATCHLIST_PANEL_ID` [#watchlist_panel_id]

```typescript
const WATCHLIST_PANEL_ID: 'vela-pro.watchlist';
```

## Namespaces [#namespaces]

### `watchlistModel` [#watchlistmodel]

```typescript
namespace watchlistModel {
    function activeList(s: WatchlistState): Watchlist;
    function addList(s: WatchlistState, name: string, entries?: WatchlistEntry[]): WatchlistState;
    function addSection(s: WatchlistState, title: string, afterIndex?: number): WatchlistState;
    function addSymbol(s: WatchlistState, symbol: string, afterIndex?: number): WatchlistState;
    const DEFAULT_COLUMNS: Record<WatchlistColumnId, boolean>;
    function deleteList(s: WatchlistState, id: string): WatchlistState;
    function emptyState(name?: string, entries?: WatchlistEntry[]): WatchlistState;
    function hasSymbol(l: Watchlist, symbol: string): boolean;
    function moveEntry(s: WatchlistState, from: number, to: number): WatchlistState;
    function newId(prefix: string): string;
    function normalizeState(raw: unknown): WatchlistState | null;
    function removeSection(s: WatchlistState, id: string): WatchlistState;
    function removeSymbol(s: WatchlistState, symbol: string): WatchlistState;
    function renameList(s: WatchlistState, id: string, name: string): WatchlistState;
    function selectList(s: WatchlistState, id: string): WatchlistState;
    function symbolsOf(l: Watchlist): string[];
    function updateSection(
        s: WatchlistState,
        id: string,
        patch: { title?: string; collapsed?: boolean },
    ): WatchlistState;
    function visibleEntries(l: Watchlist): Array<{ entry: WatchlistEntry; index: number }>;
    type WatchlistDensity = 'roomy' | 'regular' | 'compact';
    interface WatchlistLayout {
        density: WatchlistDensity;
        columns: Record<WatchlistColumnId, boolean>;
        widths: Record<WatchlistColumnId, number>;
    }
    function watchlistLayout(
        chosen: Record<WatchlistColumnId, boolean>,
        width: number | null,
    ): WatchlistLayout;
    export { LocalWatchlistStorage, MemoryWatchlistStorage };
}
```

| Member                   | Kind        | Description                                                                                                                                                                                                |
| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activeList()`           | `function`  |                                                                                                                                                                                                            |
| `addList()`              | `function`  |                                                                                                                                                                                                            |
| `addSection()`           | `function`  |                                                                                                                                                                                                            |
| `addSymbol()`            | `function`  | Add `symbol` to the active list (after `afterIndex`, else at the end). A symbol is listed once.                                                                                                            |
| `DEFAULT_COLUMNS`        | `constant`  |                                                                                                                                                                                                            |
| `deleteList()`           | `function`  | Delete a list; the last list is never deleted (it is emptied instead).                                                                                                                                     |
| `emptyState()`           | `function`  |                                                                                                                                                                                                            |
| `hasSymbol()`            | `function`  |                                                                                                                                                                                                            |
| `LocalWatchlistStorage`  | `class`     |                                                                                                                                                                                                            |
| `MemoryWatchlistStorage` | `class`     |                                                                                                                                                                                                            |
| `moveEntry()`            | `function`  | Move the entry at `from` so it lands at `to` (indices into the active list).                                                                                                                               |
| `newId()`                | `function`  |                                                                                                                                                                                                            |
| `normalizeState()`       | `function`  | A state read back from storage, made whole (a missing field takes its default).                                                                                                                            |
| `removeSection()`        | `function`  | Remove a section header; its symbols stay, joining the section above.                                                                                                                                      |
| `removeSymbol()`         | `function`  |                                                                                                                                                                                                            |
| `renameList()`           | `function`  |                                                                                                                                                                                                            |
| `selectList()`           | `function`  |                                                                                                                                                                                                            |
| `symbolsOf()`            | `function`  | The symbols of the active list in order, sections left out: what the arrow keys walk.                                                                                                                      |
| `updateSection()`        | `function`  |                                                                                                                                                                                                            |
| `visibleEntries()`       | `function`  | Entries hidden under a collapsed section.                                                                                                                                                                  |
| `WatchlistDensity`       | `type`      |                                                                                                                                                                                                            |
| `WatchlistLayout`        | `interface` |                                                                                                                                                                                                            |
| `watchlistLayout()`      | `function`  | The row layout for a panel `width` px wide: Last, Chg and Chg% stay whatever the width and a narrower panel tightens the row instead; only Volume gives way when even the tightest row has no room for it. |

See also: [`LocalWatchlistStorage`](/vela-pro/api/watchlist#localwatchliststorage), [`MemoryWatchlistStorage`](/vela-pro/api/watchlist#memorywatchliststorage), [`Watchlist`](/vela-pro/api/watchlist#watchlist-interface), [`WatchlistColumnId`](/vela-pro/api/watchlist#watchlistcolumnid), [`WatchlistEntry`](/vela-pro/api/watchlist#watchlistentry), [`WatchlistState`](/vela-pro/api/watchlist#watchliststate).

## Re-exports [#re-exports]

The following symbols are re-exported from the listed import path and documented on their primary reference page or in their upstream package.

| Export           | Kind      | Exported from                 | Documented in                                         |
| ---------------- | --------- | ----------------------------- | ----------------------------------------------------- |
| `blankQuote`     | function  | `@luxalgo/vela-pro-watchlist` | [Data feeds](/vela-pro/api/data-feeds#blankquote)     |
| `ProviderQuotes` | class     | `@luxalgo/vela-pro-watchlist` | [Data feeds](/vela-pro/api/data-feeds#providerquotes) |
| `Quote`          | interface | `@luxalgo/vela-pro-watchlist` | [Data feeds](/vela-pro/api/data-feeds#quote)          |
| `QuoteSource`    | interface | `@luxalgo/vela-pro-watchlist` | [Data feeds](/vela-pro/api/data-feeds#quotesource)    |
| `withChange`     | function  | `@luxalgo/vela-pro-watchlist` | [Data feeds](/vela-pro/api/data-feeds#withchange)     |
