# Indicator persistence (/vela-pro/persistence/stores/indicators)



When a workspace state document is restored, each chart recreates its built-in indicators, scripts from your workspace manifest, and scripts added by the user from the indicator menu, along with modified inputs and visibility state. Scripts added directly through code or executed from the code editor are not persisted automatically.

## Persisted indicator types [#persisted-indicator-types]

| Indicator category                                                                                   | State document field                                                                                      | Restoration source                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Built-in indicators (studies from Vela's open-source core and Vela Pro order-flow indicators)        | `charts[i].indicators.natives` (`type` string, or `{ type, inputs, hidden }`)                             | Registered native indicator `type`, which must be registered before `applyState()` runs                                 |
| Scripts declared in the workspace `indicators` manifest                                              | `charts[i].indicators.manifest` (`name` string, or `{ name, inputs, props, hidden }`)                     | Matching entry by `name` in your `indicators` manifest option (script source comes from the manifest, not the document) |
| Scripts added from the indicator menu (LuxAlgo library, custom menu sections, and library favorites) | `charts[i].ext['velapro.indicators']` (`{ name, script, slug, codeId, language, inputs, props, hidden }`) | Embedded `script` source stored in the document, requiring no network request on reload                                 |

The following excerpt shows the indicator fields of a single chart cell inside a state document:

```json
{
    "id": "c1",
    "indicators": {
        "manifest": ["EMA 20", { "name": "Session VWAP", "hidden": true }],
        "natives": ["volume", { "type": "rsi", "inputs": { "length": 21 } }, "vela-pro.trading"]
    },
    "ext": {
        "velapro.indicators": [{ "name": "Desk levels", "script": "//@version=5\nindicator(\"Desk levels\", overlay = true)\n..." }]
    }
}
```

Vela Pro renders on-chart order and alert lines as built-in indicators under the types `vela-pro.trading` and `vela-pro.alerts`, so those identifiers can appear in `natives`.

<Warning>
  Manifest scripts are matched by their `name` property. If you rename an entry in your `indicators` manifest, returning users' saved references to the old name are skipped on restore and omitted on the next save. Treat manifest `name` values as stable identifiers.
</Warning>

## Non-persisted scripts [#non-persisted-scripts]

Vela Pro identifies indicator menu scripts by exact source match. A script running on a chart is written to `velapro.indicators` only when that exact source string was added from the indicator menu or restored from a state document earlier in the session. Other scripts remain on the chart only until the page reloads:

* **Scripts executed from the code editor**: The editor persists its text buffer as a draft rather than persisting the chart indicator instance. Editing a menu script in the code editor and clicking Update modifies its source, so it is treated as an editor script from that point on.
* **Custom script favorites**: Starring a custom script in the code editor or on a chart legend row saves the favorite in the favorites store so the user can re-add it later, but does not add the running instance to `velapro.indicators`.
* **Template-only scripts**: Scripts applied exclusively from an indicator template are excluded unless their source was also added from the menu or restored from a document during the session. See [Indicator templates](/vela-pro/persistence/stores/indicator-templates#template-schema).
* **Programmatic scripts**: Scripts added via `chart.addIndicator()` or `ctx.addIndicator()`.

To persist custom scripts across reloads, use one of three integration seams:

* **Workspace `indicators` manifest**: Best for a fixed set of scripts shipped by your application, matched by `name`.
* **Custom indicator menu sections** (`indicatorLibrary: { sections }`): Best for user-saved scripts stored in your backend. Scripts added from a custom section serialize their source into `velapro.indicators` identically to LuxAlgo library scripts. See [Indicator menu](/vela-pro/indicators/library).
* **Custom state persistence handler**: Best for indicators managed programmatically by your application code. See [Plugin state](/vela-pro/persistence/stores/plugin-state).

## Inputs, properties, and visibility [#inputs-properties-and-visibility]

While an indicator is visible and all of its settings remain at their declared defaults, it serializes as a bare `type` or `name` string. When modified, it serializes as an object containing only the non-default fields:

* `inputs` and `props` record only values that differ from the defaults declared by the script or built-in indicator. Because unmodified defaults are not frozen into saved state documents, updating a default parameter in a script automatically applies to users who never overrode that input.
* `hidden: true` restores the indicator in a hidden, suspended state so it does not execute calculations until the user shows it again.

`props` stores script-level declaration properties, such as a strategy's initial capital or order sizing settings.

## Indicator IDs and language keys [#indicator-ids-and-language-keys]

**Runtime indicator IDs are not persisted.** Each chart generates a runtime `id` when an indicator mounts, and that ID remains stable only while the indicator stays on the chart during the current session. If your application links external state to a programmatic indicator, supply a deterministic `id` when adding it:

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

enableVelaPro();

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

const source = `//@version=5
indicator("Trend filter", overlay = true)
plot(ta.ema(close, 50))`;

const chart = workspace.chart;
const handle = chart.addIndicator(source, { id: 'acme:trend-filter', language: 'pine' });
handle.on('error', ({ error }) => console.warn('Trend filter failed:', error.message));

chart.on('indicator:error', ({ id, error }) => {
    console.warn(`Indicator ${id} on chart ${workspace.active.id} failed:`, error.message);
});
```

Passing an `id` that already exists on the chart causes `addIndicator` to throw. Programmatic indicators are not saved automatically by the workspace, so pair custom IDs with a `cell`-scoped persistence handler that calls `ctx.addIndicator({ id, ... })` on restore. See [Plugin state](/vela-pro/persistence/stores/plugin-state) for a complete example.

**The `language` key selects the scripting engine.** Manifest entries read `language` from the manifest definition. Scripts added from custom menu sections save the section's `language`, and entries without an explicit `language` default to `'pine'` (Pine Script®). Register every required engine before applying a state document (`enableVelaPro()` registers the default Pine Script® engine, while custom engines are passed through the workspace `engines` option).

## Error handling on restore [#error-handling-on-restore]

State documents restore indicators individually so a failing entry never blocks the rest of the chart:

| Failure condition                                                                                          | Behavior on restore                                                                                                  |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Script fails to compile, or no engine is registered for its `language`                                     | The chart emits `indicator:error` with `{ id, error }`, emits `error` on the indicator handle, and logs the failure. |
| Manifest `name` is no longer present in the workspace `indicators` manifest                                | The entry is skipped.                                                                                                |
| Built-in `type` is not registered (for example, an order-flow indicator when `orderflowIndicators: false`) | The indicator does not mount.                                                                                        |

## Indicator favorites [#indicator-favorites]

Favorite indicators belong to the user rather than an individual layout and persist in a separate page-level store (`localStorage` under `vela-pro-indicator-favorites` by default). Star buttons in the indicator menu, chart legend rows, and code editor header all share this store.

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

const favorites: IndicatorFavoritesStorage = {
    async load() {
        const res = await fetch('/api/users/me/indicator-favorites');
        return res.ok ? ((await res.json()) as IndicatorFavorite[]) : [];
    },
    async save(list) {
        await fetch('/api/users/me/indicator-favorites', {
            method: 'PUT',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify(list),
        });
    },
};

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

`load()` runs once when `enableVelaPro()` is called, and `save(list)` receives the full favorites array 400 ms after the most recent change. Both methods support synchronous values or promises. Any star toggled before an asynchronous `load()` resolves is merged on top of the loaded list. If `load()` or `save()` fails, Vela Pro logs the error and keeps changes in memory for the current session.

Each `IndicatorFavorite` has the shape `{ id, name, script? }`, where the `id` prefix determines how the indicator is re-added:

| `id` format     | Favorite category                              | How it is re-added                                       |
| --------------- | ---------------------------------------------- | -------------------------------------------------------- |
| `native:<type>` | Built-in indicator                             | Mounted by its registered native `type`                  |
| `slug:<slug>`   | LuxAlgo library script                         | Fetched from the LuxAlgo library by `slug`               |
| `source:<hash>` | Custom script (with source stored in `script`) | Executed from the stored `script` string as Pine Script® |

Call `indicatorFavorites()` to read or update favorites programmatically via `list()`, `has(id)`, `toggle(favorite)`, and `subscribe(listener)`.

## Related [#related]

* [Indicator menu](/vela-pro/indicators/library)
* [Pine code editor](/vela-pro/indicators/pine/code-editor)
* [Indicator templates](/vela-pro/persistence/stores/indicator-templates)
* [Indicator manifest in the core workspace guide](/vela/user/workspace#the-indicator-manifest)
