Overview
Reference for all state persisted by Vela Pro, default browser storage keys, and options for moving storage to a server.
User state in Vela Pro falls into two categories: a single workspace state document per workspace, and independent stores for data that is not scoped to a single layout. By default, independent stores write to localStorage, and the workspace state document writes to localStorage once persist is enabled. You can replace each store with a custom adapter or port to persist state per user on your backend.
State inventory
Workspace state document
These entries are scoped to a layout. Configuring persist and storage on VelaWorkspace saves and restores all of them together.
| State | Document field |
|---|---|
| Grid layout, splitter sizes, active chart, sync links, and time zone | layout, trackSizes, activeCellId, sync, timezone |
| Per-chart symbol, timeframe, chart type, session, bar depth, status line, watermark, and legend toggles | charts[i] |
| Chart settings (colors, scales, grid, margins) and chart-type settings (Footprint, TPO) | charts[i].rendererConfig |
| Drawings on each chart for its active symbol | charts[i].drawings |
| Built-in indicators and manifest scripts, including modified inputs and visibility state | charts[i].indicators |
| Scripts added from the indicator menu, including their source code | charts[i].ext['velapro.indicators'] |
| Favorite drawing tools | favorites |
| Favorite timeframes | timeframeFavorites |
| Drawing tool defaults, saved styles, magnet mode, and stay-in-drawing-mode | drawingTools |
| Side panels (active panel, resized widths, and pinned panels) | panels |
| Bottom dock open state, active panel, and height | ext['velapro.bottomDock'] |
| Order book settings (DOM columns, depth mode, combined book) | ext['velapro.orderbook'] |
| Trading settings (modified display settings, safety settings, presets, order size) | ext['velapro.trading'] |
| Calendar settings (active tab and impact filter) | ext['velapro.calendar'] |
Independent stores
| State | Default localStorage key | Scope | Configuration option or port |
|---|---|---|---|
| Per-symbol drawings across every symbol opened on a chart | vela-pro.drawings:<chart>:<symbol>, one entry per chart and symbol | Chart key and symbol | symbolDrawings: { storage } |
| Indicator templates | velapro.indicatorTemplates | User | indicatorTemplates: { storage } |
| Favorite indicators and scripts starred in the code editor | vela-pro-indicator-favorites | User | indicatorLibrary: { favorites } |
| Code editor draft | vela-pro-editor | User | codeEditor: { storage, persist } |
| Watchlists, plus column, sparkline, and detail-panel toggles | velapro.watchlists | User | watchlist: { storage } (WatchlistStorage port) |
| Alerts and alert firing log | vela-pro.alerts | User | alerts: { backend } (AlertsBackend port) |
| Journal accounts, fills, annotations, and notes | vela-pro.journal | User | journal({ store }) (JournalStore port) |
| Paper trading accounts | vela-pro.paper, vela-pro.paper:accounts, and vela-pro.paper:<account> per added account | Browser | trading({ paper: { persist } }) renames the key or keeps accounts in memory. Live accounts reside at your broker (Broker port) |
| Replay bar position and docked or floating state | vela-pro.replay.bar-position, vela-pro.replay.docked | Browser | Browser-only (not configurable) |
| Indicator menu view mode (cards or list) | velapro.indicators.layout | Browser | Browser-only (not configurable) |
User-scoped stores are isolated per signed-in user only after you connect them to your backend. With the default localStorage adapters, everyone using the same browser profile shares the stored data.
Workspace state document
workspace.getState() returns the workspace state document, and workspace.applyState() restores it as a single JSON object covering the layout and every chart in the workspace. When persist is enabled, the workspace writes the document through a storage adapter (defaulting to localStorage under the vela-workspace key) and restores it during construction.
Vela Pro features and modules with layout-level preferences store their settings inside the document's ext maps (one at the document root and one per chart). Enabling persist: true therefore preserves settings such as order book columns and trading presets automatically. See Layouts and chart state for the document schema and Plugin state to register custom state handlers.
Independent stores
State that spans multiple layouts is stored outside the workspace state document:
- Per-symbol drawings persist across symbol changes. While the state document holds one drawing set per chart for its active symbol, the per-symbol store keeps a separate set for every symbol opened on that chart and restores it when the user switches back. See Drawing persistence.
- Indicator templates and favorites apply across layouts so a template saved in one layout is available in every other layout.
- Module data represents user records rather than layout preferences. Watchlists, alerts, and journal entries remain consistent regardless of which layout is active and can render inside standalone widgets on pages without a workspace.
Each independent store accepts a small storage adapter for built-in features or a typed port interface for domain modules, defaulting to localStorage.
Transient state
| Transient state | Behavior on reload |
|---|---|
| Visible range (scroll position and zoom) | Never persisted. The visibleRange option frames the initial load of a newly created chart only. |
| Historical bars | The state document records each chart's symbol, provider, and timeframe, while OHLCV bars are fetched from your data provider on every load. |
| Theme and locale | Not stored in the state document. Each chart's rendererConfig preserves plot colors, while the surrounding interface follows the theme and locale options passed at construction. Persist the user's preference in your application and pass it when creating the workspace. |
| Maximized chart or panel | Resets to the full multi-chart layout after reload. |
| Drawing groups in the object tree | Kept in memory for the lifetime of the chart instance. |
| Scripts executed from the code editor | The editor text is saved as a draft, but indicators added directly by running code in the editor are excluded from the state document. See Indicator persistence for details. |
Moving storage to a backend
Configure a workspace storage adapter
Pass persist and a storage object implementing get and set to new VelaWorkspace(...). This routes the workspace state document and all layout-level ext settings to your backend.
Configure feature stores and module ports
Pass custom storage adapters and module ports to enableVelaPro() for symbolDrawings, indicatorTemplates, indicatorLibrary, codeEditor, and the watchlist, alerts, and journal modules.
See Server-side storage for a complete implementation covering both steps.
Related
iOS and Android WebViews
Embed Vela Pro inside iOS WKWebView and Android WebView containers with proper origin setup, runtime permissions, and a JavaScript message bridge.
Layouts and chart state
Read, save, and restore the workspace state document covering the grid layout, chart settings, drawings, and indicators.