Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo
Symbols and sessions

Symbol search

Configure, extend, programmatically control, or replace the Vela Pro symbol picker.

View as Markdown

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.

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

Each result row corresponds to one SymbolDescriptor returned by listSymbols.

FieldRole in the picker
tickerPrimary symbol identifier matched first during search and loaded on selection.
descriptionSecondary label displayed beside or below the ticker and matched after ticker text.
typeAsset class used to assign the row's category tab and market badge.
prefixVenue name shown on the row and in the venue filter. Defaults to the provider's registration key when omitted.
group, defaultGroups futures contracts under an expandable root row (ticker === group). Selecting the root loads the contract marked default: true.
marketDisplayed 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:

typeCategory tabRow badge
stockStocksStock
etf, fundETFsETF
cryptoCryptoSpot
futures, rootFuturesFutures
forexForexForex
commodityCommoditiesCommodity
economicEconomicEconomic
Any other valueAll onlyOther

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 for symbol resolution rules.

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.

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 in the core documentation.

Configuration options

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

OptionDefaultDescription
pickerBuilt-in SymbolPickerFactory function that constructs the workspace picker. Provide a custom factory to replace the built-in UI.
inspectortrueDisplays the side inspector panel next to search results on desktop viewports.
quotesDerived from workspace providersQuoteSource instance for the inspector quote card, or false to hide the quote card. See Quotes and market depth.
sparklinetrueRenders the recent daily-close sparkline beneath the inspector quote price.
venueIconundefinedCallback (venue: string) => string | undefined returning an icon URL rendered beside venue names.
takeOvertrueReplaces the core symbol search dialog across all workspace entry points.
indicatorInputstrueConnects 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

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.

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

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.

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),
    });
});
modeSelection 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

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).

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.

On this page