# Indicator menu (/vela-pro/indicators/library)



Vela Pro replaces the indicator picker from Vela's open-source core with a multi-tab menu covering built-in studies, order-flow indicators, the LuxAlgo library, user favorites, and custom script catalogs. The menu is enabled by default when you call `enableVelaPro()`. The example below registers a custom script tab and persists favorites to an application backend:

```ts
import { enableVelaPro, type IndicatorFavorite, type IndicatorMenuSection } from '@luxalgo/vela-pro';

const catalog = new Map([
    ['ema-ribbon', { name: 'EMA Ribbon', source: '//@version=6\nindicator("EMA Ribbon", overlay=true)\nplot(ta.ema(close, 20))\nplot(ta.ema(close, 50))' }],
    ['range-pct', { name: 'Range %', source: '//@version=6\nindicator("Range %")\nplot((high - low) / close * 100)' }],
]);

const acmeScripts: IndicatorMenuSection = {
    id: 'acme',
    label: 'Acme scripts',
    list: () => [...catalog].map(([id, script]) => ({ id, name: script.name })),
    source: (id) => {
        const script = catalog.get(id);
        if (!script) throw new Error(`Unknown script: ${id}`);
        return script.source;
    },
};

enableVelaPro({
    indicatorLibrary: {
        sections: [acmeScripts],
        favorites: {
            load: async () => (await fetch('/api/me/indicator-favorites')).json() as Promise<IndicatorFavorite[]>,
            save: async (favorites) => {
                await fetch('/api/me/indicator-favorites', { method: 'PUT', body: JSON.stringify(favorites) });
            },
        },
    },
});
```

Call `enableVelaPro()` before constructing a workspace, since workspaces read the registered plugin descriptors during initialization.

## Features [#features]

Users open the menu from the **Indicators** button in the topbar, with the `/` keyboard shortcut, or from the Indicators action on mobile layouts. On desktop viewports, the dialog renders three columns (a navigation rail, an item list or card grid, and a detail pane for the highlighted indicator). The rail is organized into four groups:

| Group    | Tabs                                   | Contents                                                                                                                                                     |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Yours    | Favorites, followed by custom sections | Starred indicators and any custom catalogs configured in `sections`.                                                                                         |
| Built-in | Basic, Order flow                      | Native indicators supported by the active chart's symbol; see [Built-in indicators](/vela-pro/indicators/included).                                          |
| Library  | Discover, All scripts, Concepts        | LuxAlgo library scripts, including recent releases, the full catalog (sortable newest-first or alphabetically, as cards or list rows), and trading concepts. |
| Families | One tab per library family             | LuxAlgo library scripts in that family, with concept filter chips.                                                                                           |

The dialog opens on Discover by default. Clicking an entry adds the indicator to the active chart and closes the dialog.

Typing in the search input queries built-in indicators, custom sections, library scripts, and library concepts simultaneously. Matching entries are grouped under section headings (custom sections, Built-in, Library, and Concepts). Built-in indicators also match on acronyms, so typing `atr` surfaces Average True Range. Library search runs on the server with a 300 ms debounce after the last keystroke.

| Shortcut          | Action                                                         |
| ----------------- | -------------------------------------------------------------- |
| `↑` `↓`           | Move selection up or down.                                     |
| `Enter`           | Add the highlighted indicator and close the menu.              |
| `Shift` + `Enter` | Add the highlighted indicator and keep the menu open.          |
| `F`               | Star or unstar the highlighted indicator.                      |
| `/`               | Focus the search input.                                        |
| `Esc`             | Clear the search query if non-empty, otherwise close the menu. |

Adding an indicator from the menu records an entry in the workspace undo history and saves the indicator in the workspace state document so it is restored on reload; see [Indicator persistence](/vela-pro/persistence/stores/indicators).

## Favorites [#favorites]

Users can star or unstar an indicator from three surfaces: rows, cards, and the detail pane inside the indicator menu; the legend row of a native or Pine Script® indicator; and the header of the Pine code editor. All three surfaces read and write the same favorites store, which populates both the Favorites tab in the menu and the quick-access dropdown opened by the chevron beside the topbar Indicators button.

Each favorite is stored as an `IndicatorFavorite` object:

```typescript
interface IndicatorFavorite {
    id: string;      // 'native:rsi', 'slug:squeeze-index', or 'source:<hash>'
    name: string;    // Display label in the Favorites tab
    script?: string; // Pine Script® source code for 'source:' entries
}
```

A `source:` favorite captures an immutable snapshot of the script text at the moment it was starred. Editing the script later and starring it again creates a separate favorite entry under the new content hash.

### Server-side favorites storage [#server-side-favorites-storage]

By default, favorites are stored in browser `localStorage` under the key `vela-pro-indicator-favorites`. Pass a custom storage adapter in `favorites` to persist favorites per user on your backend, as shown in the example at the top of this page:

* `load()` runs once when `enableVelaPro()` is called and returns the initial array (or a Promise resolving to it).
* `save(favorites)` receives the full array 400 ms after the most recent change.

Both methods may be synchronous or asynchronous. The UI never blocks on storage I/O; if a user toggles a star before `load()` settles, the change is merged onto the loaded list once it arrives. If either call throws or rejects, Vela Pro logs a console warning and retains the in-memory favorites for the current page session.

Because `load()` executes during `enableVelaPro()` before any workspace mounts, user authentication state must already be available if your endpoint requires it. You can also read, toggle, and subscribe to favorites programmatically with `indicatorFavorites()`:

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

const favorites = indicatorFavorites();
const stop = favorites.subscribe(() => console.log(favorites.list().map((favorite) => favorite.name)));

favorites.toggle({ id: 'native:rsi', name: 'Relative Strength Index' }); // returns true when added
stop();
```

## Custom catalog sections [#custom-catalog-sections]

Each `IndicatorMenuSection` passed in `sections` adds a custom tab to the menu rail and delegates catalog loading to two callbacks:

* `list()` returns `{ id, name }[]` and runs every time the menu opens so the catalog stays current. While a returned Promise is pending, the tab displays a loading indicator; if the Promise rejects, the tab displays an unreachable state with the error message.
* `source(id)` runs when the user selects a row and returns the script string to execute. If it throws or rejects, the row displays **Failed, try again**.

Both callbacks can return a synchronous value or a Promise. Rows from custom sections are included in menu search results, and any script added from a custom section persists its source code and engine language in the workspace state document. Rows inside custom sections do not show a favorites star.

| Property     | Default                 | Description                                                                                                                                                                                       |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | required                | Unique, stable identifier for the section.                                                                                                                                                        |
| `label`      | required                | Tab label displayed in the navigation rail.                                                                                                                                                       |
| `group`      | Yours (after Favorites) | Pass `'library'` to place the tab at the end of the Library group instead.                                                                                                                        |
| `language`   | `'pine'`                | Language key of the scripting engine that runs scripts returned by `source(id)`. Set this when serving scripts for a custom engine; see [Custom runtimes](/vela-pro/indicators/runtimes/engines). |
| `list()`     | required                | Returns the list of `{ id, name }` entries for the tab.                                                                                                                                           |
| `source(id)` | required                | Returns the script source string for a selected entry.                                                                                                                                            |

## Options [#options]

Configure the menu via `enableVelaPro({ indicatorLibrary: { ... } })`, or pass the same options to `enableIndicatorLibrary()` when enabling features individually.

| Option       | Default                            | Description                                                                                                                         |
| ------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `sections`   | `undefined`                        | Custom `IndicatorMenuSection` tabs added to the menu rail.                                                                          |
| `favorites`  | `localIndicatorFavoritesStorage()` | Storage adapter used to load and save starred indicators.                                                                           |
| `libraryUrl` | `'https://app.luxalgo.com'`        | Base origin for LuxAlgo library requests (`/api/library/...`). Point this to a same-origin proxy when serving from a custom domain. |
| `basics`     | `BASIC_INDICATORS`                 | LuxAlgo library scripts (`{ name, slug }`) shown alongside native studies in the Basic tab. Pass `[]` to list only native studies.  |

The menu fetches the LuxAlgo library catalog when a user browses the Library tabs and fetches an individual script's source when the user adds it. If the library origin is unreachable, only the Library tabs report an offline state while built-in indicators, favorites, and custom sections continue working normally. Library scripts already mounted on a chart are unaffected because their source is stored in the workspace state document.

<Note>
  Browsers block direct cross-origin requests from third-party domains to `https://app.luxalgo.com`, causing the Library tabs to display "The library is unreachable". To serve the LuxAlgo library in your application, set `libraryUrl` to a proxy route on your domain that forwards `/api/library/...` requests to `https://app.luxalgo.com`.
</Note>

The indicator menu replaces the `'indicators'` action in the topbar, so workspace `topbar` configuration controls its visibility and placement in the same way as the default button. Vela Pro exports its action identifier as `INDICATOR_MENU_ACTION_ID`; see [Interface layout](/vela-pro/customization/interface) for topbar customization.

## Using the default core picker [#using-the-default-core-picker]

Pass `indicatorLibrary: false` to disable the Vela Pro indicator menu and keep the default picker from the core:

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

enableVelaPro({ indicatorLibrary: false });
```

With the Vela Pro menu disabled, the topbar **Indicators** button opens the core picker, which lists supported native indicators (including Vela Pro's order-flow indicators) and scripts declared in your workspace [indicator manifest](/vela/user/workspace#the-indicator-manifest). Disabling the menu also removes the LuxAlgo library tabs, custom `sections`, and the favorites star on legend rows.

<Note>
  The Vela Pro indicator menu does not list entries from the workspace `indicators` manifest. Manifest entries with `enabled: true` are still added automatically to every new chart, while entries with `enabled: false` have no menu row to pick them from. Expose selectable scripts through `sections` when using the Vela Pro menu.
</Note>

## Related [#related]

* [Built-in indicators](/vela-pro/indicators/included)
* [Pine code editor](/vela-pro/indicators/pine/code-editor)
* [Indicator persistence](/vela-pro/persistence/stores/indicators)
