# Symbol search (/vela-pro/data/symbols/symbol-search)



Calling `enableVelaPro()` replaces the default symbol search in Vela's open-source core with the Vela Pro symbol picker. The picker provides a search input, market category tabs, a venue filter, and a side inspector panel showing the highlighted symbol's live quote, instrument metadata, and alternative venue listings. It populates automatically from the `SymbolDescriptor` entries returned by each provider's `listSymbols` method.

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro({
    symbolSearch: {
        sparkline: false, // keep quote price and change, hide the recent-closes sparkline
        venueIcon: (venue) => `https://cdn.example.com/venues/${venue.toLowerCase()}.svg`,
    },
});
```

Users can open the picker from the top bar symbol button, by typing alphanumeric characters while the chart is focused, from symbol inputs inside indicator settings, or from the Add Symbol button in the watchlist. Host code can also open it through `ctx.openSymbolSearch()` or `symbolPicker()`. Full keyboard navigation is built in (`ArrowUp`, `ArrowDown`, `PageUp`, and `PageDown` move through results, `Enter` selects the highlighted symbol, `Tab` switches market tabs, and `Escape` closes the dialog). On phone viewports, the picker renders full-screen and hides the side inspector panel.

## Provider descriptor fields [#provider-descriptor-fields]

Each result row corresponds to one `SymbolDescriptor` returned by `listSymbols`.

| Field              | Role in the picker                                                                                                                        |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `ticker`           | Primary symbol identifier matched first during search and loaded on selection.                                                            |
| `description`      | Secondary label displayed beside or below the ticker and matched after ticker text.                                                       |
| `type`             | Asset class used to assign the row's category tab and market badge.                                                                       |
| `prefix`           | Venue name shown on the row and in the venue filter. Defaults to the provider's registration key when omitted.                            |
| `group`, `default` | Groups futures contracts under an expandable root row (`ticker === group`). Selecting the root loads the contract marked `default: true`. |
| `market`           | Displayed as **Product** inside the inspector details section.                                                                            |

Although `type` is an unconstrained string in the core, the Vela Pro picker maps these values (case-insensitively) to category tabs:

| `type`            | Category tab | Row badge |
| ----------------- | ------------ | --------- |
| `stock`           | Stocks       | Stock     |
| `etf`, `fund`     | ETFs         | ETF       |
| `crypto`          | Crypto       | Spot      |
| `futures`, `root` | Futures      | Futures   |
| `forex`           | Forex        | Forex     |
| `commodity`       | Commodities  | Commodity |
| `economic`        | Economic     | Economic  |
| Any other value   | All only     | Other     |

Any `crypto` or `futures` symbol whose `ticker` ends in `.P`, or whose `description` contains `"perpetual"` (case-insensitive), is categorized under the **Crypto** tab with the badge **Perpetual**. Category tabs appear only when at least one listed symbol belongs to that category. Symbol logos resolve via your provider's `resolveSymbolIcon` method and fall back to ticker initials.

Selecting a row always commits the venue-prefixed identifier (`NASDAQ:AAPL`, `acme:BTCUSDT`) so that shared tickers listed by multiple providers always resolve to the chosen venue. See [Symbology](/vela-pro/data/symbols/symbology) for symbol resolution rules.

### Search ranking and default ordering [#search-ranking-and-default-ordering]

When the search query is empty, the picker surfaces a built-in priority list of major benchmark tickers first (`BTCUSDT`, `AAPL`, `SPY`, `ES1!`, `EURUSD`, and others) at their first available listing, provided your registered providers include them. All remaining symbols appear in provider registration order, preserving the array order returned by each provider's `listSymbols` call. Return your primary instruments first from `listSymbols` to display them near the top of the default view.

As the user types, the core search ranker orders matches by exact ticker match, ticker prefix match, ticker substring match, description substring match, and venue name match. Starting the query with a venue name (`nasdaq aap` or `nasdaq:aap`) restricts matches to listings on that venue.

<Note>
  The core `registerSymbolRanking` hook applies only to the core search dialog shown when `symbolSearch: false` or `takeOver: false`. The Vela Pro symbol picker does not read it. See [Symbol ranking](/vela/contributing/plugin-sdk#symbol-ranking--registersymbolranking) in the core documentation.
</Note>

## Configuration options [#configuration-options]

Pass symbol search options under `symbolSearch` in `enableVelaPro()`, or set `symbolSearch: false` to retain the core search dialog.

| Option            | Default                          | Description                                                                                                                                                   |
| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `picker`          | Built-in `SymbolPicker`          | Factory function that constructs the workspace picker. Provide a custom factory to replace the built-in UI.                                                   |
| `inspector`       | `true`                           | Displays the side inspector panel next to search results on desktop viewports.                                                                                |
| `quotes`          | Derived from workspace providers | `QuoteSource` instance for the inspector quote card, or `false` to hide the quote card. See [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth). |
| `sparkline`       | `true`                           | Renders the recent daily-close sparkline beneath the inspector quote price.                                                                                   |
| `venueIcon`       | `undefined`                      | Callback `(venue: string) => string \| undefined` returning an icon URL rendered beside venue names.                                                          |
| `takeOver`        | `true`                           | Replaces the core symbol search dialog across all workspace entry points.                                                                                     |
| `indicatorInputs` | `true`                           | Connects symbol input fields inside indicator settings dialogs to the Vela Pro picker.                                                                        |

In modular setups that do not call `enableVelaPro()`, pass the same options object to `enableSymbolSearch(options)`.

## Custom inspector sections [#custom-inspector-sections]

By default, the inspector panel renders the quote card, symbol details (venue, market, product), and alternative venue listings. Call `registerSymbolPickerSection` to inject custom DOM sections for the highlighted symbol.

```ts
import { registerSymbolPickerSection } from '@luxalgo/vela-pro';

declare const margins: Map<string, string>; // custom metadata keyed by ticker

registerSymbolPickerSection({
    id: 'acme.margin',
    order: 20, // after details (10), before other listings (50)
    render(symbol) {
        const margin = margins.get(symbol.ticker);
        if (!margin) return null; // omit section for this symbol
        const row = document.createElement('div');
        row.textContent = `Initial margin: ${margin}`;
        return row;
    },
});
```

`render(symbol, ctx)` executes synchronously whenever the highlighted symbol changes and returns either an `HTMLElement` or `null` to skip rendering for that symbol. If your section fetches asynchronous data, return a container element immediately and populate it when the request resolves. The `ctx` parameter exposes `pool()` (all listed symbols), `select(symbol)` (commits a symbol as if clicked), `logo(symbol, size)`, and `shell` (the workspace `WidgetContext`).

Sections sort in ascending `order` (`0` for the quote card, `10` for details, `50` for other listings, and last when `order` is omitted). Re-registering an existing `id` replaces the previous section, and calling the disposer returned by `registerSymbolPickerSection` unregisters it. Sections that throw an exception are skipped with a console warning.

## Programmatic control [#programmatic-control]

Call `symbolPicker(shell)` to obtain the picker controller for a workspace. Pass `workspace.root` or the `WidgetContext` received by a custom widget action or side panel.

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

enableVelaPro();

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

document.querySelector('#compare')?.addEventListener('click', () => {
    symbolPicker(workspace.root)?.open({
        mode: 'select',
        query: 'ETH',
        onSelect: (symbol, descriptor) => console.info(symbol, descriptor.description),
    });
});
```

| `mode`              | Selection behavior                                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'chart'` (default) | Closes the picker and loads the chosen symbol on the active chart, or invokes `onSelect` when provided.                                                        |
| `'select'`          | Closes the picker and passes `(symbol, descriptor)` to `onSelect`.                                                                                             |
| `'watchlist'`       | Keeps the picker open for multi-symbol editing. Each row displays an add or remove toggle controlled by `isListed(symbol)` and `onToggle(symbol, descriptor)`. |

`symbolPicker` returns `null` when symbol search is disabled.

## Custom picker implementation [#custom-picker-implementation]

Supplying a `picker` factory replaces the built-in dialog while routing all workspace triggers to your implementation. The factory receives the workspace `WidgetContext` and returns a `SymbolPickerLike` controller (`open`, `close`, `isOpen`, and `destroy`).

```ts
import { enableVelaPro, searchSymbols, symbolOf, type SymbolPickerLike } from '@luxalgo/vela-pro';

const TOP = ['AAPL', 'MSFT', 'EURUSD']; // surfaced first when query is empty

enableVelaPro({
    symbolSearch: {
        picker: (ctx): SymbolPickerLike => {
            const dialog = ctx.host.appendChild(document.createElement('dialog'));
            return {
                open(opts = {}) {
                    const { rows } = searchSymbols(ctx.chart.data.symbols(), { text: opts.query ?? '', limit: 20 }, TOP);
                    const buttons = rows.map((row) => {
                        const button = document.createElement('button');
                        button.textContent = `${row.ticker} ${row.description ?? ''}`;
                        button.onclick = () => {
                            dialog.close();
                            if (opts.onSelect) opts.onSelect(symbolOf(row), row);
                            else ctx.setSymbol(symbolOf(row));
                        };
                        return button;
                    });
                    dialog.replaceChildren(...buttons);
                    dialog.show();
                },
                close: () => dialog.close(),
                get isOpen() {
                    return dialog.open;
                },
                destroy: () => dialog.remove(),
            };
        },
    },
});
```

`searchSymbols(pool, query, top)` runs the same ranking algorithm as the built-in picker (accepting priority default tickers as its third argument), and `symbolOf(row)` formats the canonical venue-prefixed symbol string. A full custom picker should also support `'watchlist'` mode and resolve futures root rows (`row.ticker === row.group`) via `defaultMemberOf(pool, row)`. Implement the optional `type(text)` method on `SymbolPickerLike` to receive subsequent characters typed on the chart while the picker opens; when `type` is omitted, Vela Pro calls `open` again with the updated query string.

## Related [#related]

* [Symbology](/vela-pro/data/symbols/symbology)
* [Watchlist](/vela-pro/modules/catalog/watchlist)
* [Symbols API reference](/vela-pro/api/symbols)
