# Symbols (/vela-pro/api/symbols)



This page documents the symbol search dialog, custom symbol section descriptors, and helper functions for parsing market categories and venues from symbol identifiers.

Import symbols on this page from `@luxalgo/vela-pro`. Related guides: [Symbol search](/vela-pro/data/symbols/symbol-search), [Symbology](/vela-pro/data/symbols/symbology).

Feature enabler for this area ([`enableSymbolSearch`](/vela-pro/api/enablers#enablesymbolsearch)) is documented on [Enablers and options](/vela-pro/api/enablers).

## Functions [#functions]

### `defaultMemberOf` [#defaultmemberof]

The member a group pick loads: its single default, else its first member.

```typescript
function defaultMemberOf(
    pool: readonly SymbolDescriptor[],
    group: SymbolDescriptor,
): SymbolDescriptor | null
```

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

### `foldGroups` [#foldgroups]

Drop a member whose group's row is already listed above it: the group stands for its members.

```typescript
function foldGroups(list: readonly SymbolDescriptor[]): SymbolDescriptor[]
```

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

### `marketOf` [#marketof]

```typescript
function marketOf(d: SymbolDescriptor): SymbolMarket
```

See also: [`SymbolMarket`](/vela-pro/api/symbols#symbolmarket). From `@luxalgo/vela/plugin`: `SymbolDescriptor`.

### `otherListings` [#otherlistings]

The same instrument elsewhere: a stock's listing on another venue (same ticker), a crypto asset's pairs on other venues and its perpetuals (most liquid quotes first).

```typescript
function otherListings(
    d: SymbolDescriptor,
    pool: readonly SymbolDescriptor[],
    max?: number,
): SymbolDescriptor[]
```

Default: `max = 5`.

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

### `registerSymbolPickerSection` [#registersymbolpickersection]

Add (or replace, by id) a section of the symbol picker's inspector. Returns the removal.

```typescript
function registerSymbolPickerSection(section: SymbolPickerSection): () => void
```

See also: [`SymbolPickerSection`](/vela-pro/api/symbols#symbolpickersection).

### `searchSymbols` [#searchsymbols]

The ranked rows for a query: Vela's ranking over the tab's pool, futures contracts folded under their root.

```typescript
function searchSymbols(
    pool: readonly SymbolDescriptor[],
    q: SymbolQuery,
    top?: readonly string[],
): { rows: SymbolDescriptor[]; exhausted: boolean }
```

Default: `top = TOP_SYMBOLS`.

See also: [`SymbolQuery`](/vela-pro/api/symbols#symbolquery). From `@luxalgo/vela/plugin`: `SymbolDescriptor`.

### `symbolOf` [#symbolof]

The symbol string a pick commits: venue-pinned, so a ticker listed twice never re-resolves elsewhere.

```typescript
function symbolOf(d: SymbolDescriptor): string
```

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

### `symbolPicker` [#symbolpicker]

The symbol picker of a shell (`ctx` or its host element), once [`enableSymbolSearch`](/vela-pro/api/enablers#enablesymbolsearch) ran.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function symbolPicker(shell: WidgetContext | HTMLElement): SymbolPickerLike | null
```

See also: [`SymbolPickerLike`](/vela-pro/api/symbols#symbolpickerlike). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `venueOf` [#venueof]

The row's venue: the listing prefix the data declares, else the provider name.

```typescript
function venueOf(d: SymbolDescriptor): string
```

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

## Classes [#classes]

### `SymbolPicker` class [#symbolpicker-class]

```typescript
class SymbolPicker implements SymbolPickerLike {
    constructor(ctx: WidgetContext, opts?: SymbolPickerOptions);
    readonly isOpen: boolean;
    open(opts?: SymbolPickerOpenOptions): void;
    close(): void;
    type(text: string): void;
    destroy(): void;
}
```

| Member        | Type                                               | Description                                                           |
| ------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| `constructor` | `(ctx: WidgetContext, opts?: SymbolPickerOptions)` |                                                                       |
| `isOpen`      | `boolean`                                          |                                                                       |
| `open()`      | `(opts?: SymbolPickerOpenOptions) => void`         |                                                                       |
| `close()`     | `() => void`                                       |                                                                       |
| `type()`      | `(text: string) => void`                           | Text typed at the chart while the picker opens: it extends the query. |
| `destroy()`   | `() => void`                                       |                                                                       |

See also: [`SymbolPickerLike`](/vela-pro/api/symbols#symbolpickerlike), [`SymbolPickerOpenOptions`](/vela-pro/api/symbols#symbolpickeropenoptions), [`SymbolPickerOptions`](/vela-pro/api/symbols#symbolpickeroptions). From `@luxalgo/vela/plugin`: `WidgetContext`.

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

### `SymbolMarket` [#symbolmarket]

```typescript
type SymbolMarket =
    | 'stocks'
    | 'etfs'
    | 'crypto'
    | 'perp'
    | 'futures'
    | 'forex'
    | 'commodities'
    | 'economic'
    | 'other';
```

### `SymbolPickerLike` [#symbolpickerlike]

What Pro opens for "search a symbol": implement it to swap in a picker of your own.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface SymbolPickerLike {
    open(opts?: SymbolPickerOpenOptions): void;
    close(): void;
    readonly isOpen: boolean;
    destroy(): void;
    type?(text: string): void;
}
```

| Member      | Type                                       | Description                                                                                           |
| ----------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `open()`    | `(opts?: SymbolPickerOpenOptions) => void` |                                                                                                       |
| `close()`   | `() => void`                               |                                                                                                       |
| `isOpen`    | `boolean`                                  |                                                                                                       |
| `destroy()` | `() => void`                               |                                                                                                       |
| `type?()`   | `(text: string) => void`                   | Text typed at the chart while the picker opens; it extends the query (else the picker reopens on it). |

See also: [`SymbolPickerOpenOptions`](/vela-pro/api/symbols#symbolpickeropenoptions).

### `SymbolPickerMode` [#symbolpickermode]

```typescript
type SymbolPickerMode = 'chart' | 'watchlist' | 'select';
```

### `SymbolPickerOpenOptions` [#symbolpickeropenoptions]

```typescript
interface SymbolPickerOpenOptions {
    query?: string;
    mode?: SymbolPickerMode;
    onSelect?: (symbol: string, descriptor: SymbolDescriptor) => void;
    isListed?: (symbol: string) => boolean;
    onToggle?: (symbol: string, descriptor: SymbolDescriptor) => void;
}
```

| Member      | Type                                                     | Description                                                                                                   |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `query?`    | `string`                                                 | The search to open on.                                                                                        |
| `mode?`     | `SymbolPickerMode`                                       | `chart` (default): a pick opens it on the chart. `watchlist`: rows add and remove. `select`: report the pick. |
| `onSelect?` | `(symbol: string, descriptor: SymbolDescriptor) => void` | Called with the picked symbol (venue-pinned: `binance:BTCUSDT`, `NASDAQ:AAPL`).                               |
| `isListed?` | `(symbol: string) => boolean`                            | Watchlist mode: whether a symbol is listed, and toggling it.                                                  |
| `onToggle?` | `(symbol: string, descriptor: SymbolDescriptor) => void` |                                                                                                               |

See also: [`SymbolPickerMode`](/vela-pro/api/symbols#symbolpickermode). From `@luxalgo/vela/plugin`: `SymbolDescriptor`.

### `SymbolPickerOptions` [#symbolpickeroptions]

```typescript
interface SymbolPickerOptions {
    inspector?: boolean;
    quotes?: QuoteSource | null;
    sparkline?: boolean;
    venueIcon?: (venue: string) => string | undefined;
}
```

| Member       | Type                                     | Description                                                             |
| ------------ | ---------------------------------------- | ----------------------------------------------------------------------- |
| `inspector?` | `boolean`                                | The inspector beside the results (default true).                        |
| `quotes?`    | `QuoteSource \| null`                    | The inspector's quote. Default: none (the quote section is left out).   |
| `sparkline?` | `boolean`                                | The quote's sparkline of recent closes, under the price (default true). |
| `venueIcon?` | `(venue: string) => string \| undefined` | A venue's logo (`NASDAQ`, `binance`).                                   |

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

### `SymbolPickerSection` [#symbolpickersection]

A section of the picker's inspector, for the highlighted symbol.

```typescript
interface SymbolPickerSection {
    id: string;
    order?: number;
    render(symbol: SymbolDescriptor, ctx: SymbolPickerSectionContext): Node | null;
}
```

| Member     | Type                                                                          | Description                                                                   |
| ---------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `id`       | `string`                                                                      |                                                                               |
| `order?`   | `number`                                                                      | Sections sort by order (the built-in ones: quote 0, details 10, listings 50). |
| `render()` | `(symbol: SymbolDescriptor, ctx: SymbolPickerSectionContext) => Node \| null` |                                                                               |

See also: [`SymbolPickerSectionContext`](/vela-pro/api/symbols#symbolpickersectioncontext). From `@luxalgo/vela/plugin`: `SymbolDescriptor`.

### `SymbolPickerSectionContext` [#symbolpickersectioncontext]

```typescript
interface SymbolPickerSectionContext {
    shell: WidgetContext;
    pool(): readonly SymbolDescriptor[];
    select(symbol: SymbolDescriptor): void;
    logo(symbol: SymbolDescriptor, size?: number): HTMLElement;
}
```

| Member     | Type                                                       | Description                                 |
| ---------- | ---------------------------------------------------------- | ------------------------------------------- |
| `shell`    | `WidgetContext`                                            |                                             |
| `pool()`   | `() => readonly SymbolDescriptor[]`                        | Every symbol the providers list.            |
| `select()` | `(symbol: SymbolDescriptor) => void`                       | Pick a symbol, as a click on its row would. |
| `logo()`   | `(symbol: SymbolDescriptor, size?: number) => HTMLElement` |                                             |

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

### `SymbolQuery` [#symbolquery]

```typescript
interface SymbolQuery {
    text: string;
    tab?: string;
    venue?: string | null;
    limit?: number;
}
```

| Member   | Type             | Description                                                                     |
| -------- | ---------------- | ------------------------------------------------------------------------------- |
| `text`   | `string`         |                                                                                 |
| `tab?`   | `string`         |                                                                                 |
| `venue?` | `string \| null` | Only this venue ([`venueOf`](/vela-pro/api/symbols#venueof), case-insensitive). |
| `limit?` | `number`         |                                                                                 |

### `SymbolTab` [#symboltab]

```typescript
interface SymbolTab {
    id: string;
    label: string;
    markets: readonly SymbolMarket[] | null;
}
```

| Member    | Type                              | Description                                         |
| --------- | --------------------------------- | --------------------------------------------------- |
| `id`      | `string`                          |                                                     |
| `label`   | `string`                          |                                                     |
| `markets` | `readonly SymbolMarket[] \| null` | The markets the tab lists; null lists every market. |

See also: [`SymbolMarket`](/vela-pro/api/symbols#symbolmarket).

## Constants [#constants]

### `MARKET_LABELS` [#market_labels]

```typescript
const MARKET_LABELS: Record<SymbolMarket, string>;
```

See also: [`SymbolMarket`](/vela-pro/api/symbols#symbolmarket).

### `SYMBOL_TABS` [#symbol_tabs]

```typescript
const SYMBOL_TABS: readonly SymbolTab[];
```

See also: [`SymbolTab`](/vela-pro/api/symbols#symboltab).
