Chart State

chart.getState() returns a JSON-safe snapshot of everything the chart owns; chart.restoreState(state) puts it back. Saved layouts, chart templates, an objects panel, and drawing persistence all ride on this one pair.

localStorage.setItem('layout', JSON.stringify(chart.getState()));
 
// later, after your data has loaded
const raw = localStorage.getItem('layout');
if (raw !== null) {
  const report = chart.restoreState(JSON.parse(raw));
  if (!report.applied) showRestoreError(report.reason);
}

What is captured - and what is not

The rule: the chart serialises what the chart owns.

The settings blocks are restored before the panes, deliberately: the chart-wide plot margins land first so a pane’s own saved marginTop / marginBottom is the more specific answer and wins. A layout saved by a host that built its dialog from the settings schema therefore brings the dialog’s settings back with it, with no second store.

Navigation settings are restored before the saved viewport. A saved navigation.defaultVisibleBars therefore remains the default for future resets without replacing the exact range the user saved. Older snapshots may omit navigation; the chart keeps its current navigation options. The count controls the initial/reset view of loaded data, not the amount of history your feed requests or retains.

// On a replacement chart, recreate the sources your host owns first.
chart.setDataContext({ symbol: mySymbol, exchange: myExchange, interval: myInterval });
const price = chart.addSeries('candlestick');
price.setData(await loadBars(mySymbol, myInterval));
 
const report = chart.restoreState(saved);
if (!report.applied) showRestoreError(report.reason);

report.series describes all recorded series, including indicator-owned outputs. Do not blindly recreate every entry as a price source. Keep a host source manifest for primary, volume and comparison data; restoreState recreates registered indicator outputs itself. Reattach host controllers to a replacement chart.

RestoreReport

restoreState retains panes containing live studies even when those studies render only levels or primitives. Unavailable studies do not leave empty panes. If a state:restore:start listener installs a newer state synchronously, the older restore returns applied: false instead of overwriting it.

chart.restoreState(state, options?) accepts ChartRestoreOptions. Use preserveScaleFormats when rebuilding studies must retain the destination’s runtime formatter callback or default formatter on specific existing scales:

chart.restoreState(saved, {
  preserveScaleFormats: [{ paneIndex: 0, scaleId: 'right' }],
});

Selectors are validated before mutation and must refer to existing scales. Saved numeric scale settings still apply. The option only suppresses automatic formatter installation while study series are recreated; later explicit host formatting and study settings changes retain their usual behavior. No function is serialized. Without options, normal descriptor formatting applies.

Saved axes

PaneState.priceScale describes the right scale. Optional PaneState.scales stores the left scale and named hidden scales by their native PriceScaleId. Each PriceScaleState includes the existing scale settings plus optional minPrecision, fixedRange and ratioLock. The lock stores the bar spacing and pane height associated with its saved manual range so its proportion survives reopening at another size. These fields are additive; older layouts remain readable.

parsePaneState(value) validates and copies one pane snapshot, including its optional boolean collapsed flag. Invalid fields throw before chart restoration changes any panes. The optional second argument, true, accepts legacy partial primary-scale settings with default values; secondary scales always require complete settings. Workspace documents use the same validator. Formatter callbacks and source data remain host-owned.

When a widget restores onto a different symbol or interval, stripView removes the viewport, manual ranges and ratio locks from every scale. It retains scale formatting and declared fixed ranges while re-enabling automatic fitting.

Ordering

Logical ranges index bars, so a viewport restored onto an empty chart means nothing. The reliable sequence is:

1. Register the indicator descriptors the saved layout needs.
2. Set the chart’s data context, recreate host-owned source series, and load their bars.
3. Call restoreState(saved) and check report.applied.

If settings were restored before data loaded, restore again afterward or apply the saved viewport with setVisibleLogicalRange when it is present.

Calling restoreState twice is safe: indicators are replaced, not appended, so restore is idempotent.

Versioning and forward compatibility

Every snapshot carries a version, at most CHART_STATE_VERSION (2). A chart whose price pane is on top still writes version 1, so compare a saved version with > rather than demanding it equal the constant. A state from a newer version is rejected rather than half-applied - applied: false with a reason - so an older build reading a newer layout degrades visibly instead of silently dropping settings.

An indicator whose tier is not loaded is skipped, not thrown: restoring a layout that uses openalgo-charts/indicators in an app that has not imported the tier leaves that indicator out and restores the rest.

Saved alerts and indicator identities are validated before restoration begins. An invalid alert document or a duplicate indicator instance ID rejects the snapshot before changing the chart. During controller restore, a registered provider that reports a missing study, plot or drawing causes that alert to be dropped with an alert:removed reason. If the required provider itself is absent, the record is retained but unavailable. Neither path binds to another object by name.

Alerts and named workspaces

ChartState.alerts is the controller’s committed alert document. A threshold drag changes only its visual preview until release; cancellation leaves the saved state untouched. Restore preserves triggered and disabled state and does not deliver notifications for historical matches. See Alerts for controller ownership, source availability and host delivery.

For a named layout spanning multiple charts, source requests and link settings, use the optional workspace tier. ChartState is one chart’s snapshot; it does not contain feed credentials or the bars themselves. Exporting loaded observations as CSV is a separate chart data export.

The drawings slot

ChartState.drawings is an opaque passthrough. The base engine stores and returns it untouched; the drawing tier reads and writes it. That means an app which already persists chart state keeps drawings for free once the tier is loaded, with no new storage plumbing.

chart.setDrawingState(payload);   // what the drawing tier does
chart.drawingState();             // read it back

The slot holds one document, the drawings on screen, whatever instrument the chart shows. A host that loads several symbols into one chart keeps a document per symbol with the draw tier’s InstrumentDrawings, which the widget uses by default (since 2.5.9): the state then carries the drawings of the instrument in its data context.

Coordinate helpers

State restore and drawing anchors both need to convert between time and screen x. Because the time axis is gapless - weekends, holidays, and session breaks collapse - many x positions have no bar behind them, so the whole-index helpers are not enough.

coordinateToTime is what makes a two-axis drag work: chart.subscribeDrag passes the time under the cursor as a third argument alongside the price, so a trendline endpoint or a forward projection has a usable time even where no bar exists.

chart.subscribeDrag(
  (id, price, time) => moveAnchor(id, { time, price }),
  (id, price, time) => commitAnchor(id, { time, price }),
);