Indicator persistence
How built-in indicators, manifest scripts, menu scripts, and indicator favorites are serialized and restored across reloads.
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
| 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:
{
"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.
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.
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.
- Programmatic scripts: Scripts added via
chart.addIndicator()orctx.addIndicator().
To persist custom scripts across reloads, use one of three integration seams:
- Workspace
indicatorsmanifest: Best for a fixed set of scripts shipped by your application, matched byname. - Custom indicator menu sections (
indicatorLibrary: { sections }): Best for user-saved scripts stored in your backend. Scripts added from a custom section serialize their source intovelapro.indicatorsidentically to LuxAlgo library scripts. See Indicator menu. - Custom state persistence handler: Best for indicators managed programmatically by your application code. See Plugin state.
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:
inputsandpropsrecord 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: truerestores 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
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:
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 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
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
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.
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
Configuration precedence
Precedence rules between constructor options, saved workspace state documents, per-symbol drawing storage, and runtime API calls.
Drawing persistence
Configure per-symbol drawing storage, workspace state document persistence, chart and symbol keys, and conflict resolution rules.