Plot action

Use this action with change({ id: 'Plot', context }).

Context

Key fields:

• id: Add | Get | Delete | Update
• selectors: main, uid, index, type
• payload fields (sub-action/type dependent):
  • creation keys: studyId, fundamentalId, symbol, expression, seasonal
  • update keys: forward, seasonal, expression, symbol, frequency, visible, precision, showPrevious
  • style/data keys: inputs, curves, offsets, levels, bands, basis
  • placement keys: placement, paneIndex, oppositeScale, cloneUid, cloneIndex

Behavior

Plot is a multi-action API for creating and maintaining chart plots.

Sub-actions

Get

Returns plot data without changing chart state.

• Use main: true to retrieve the main plot.
• You can target a specific plot by uid (preferred) or index.
• Returned items are normalized plot objects that include identity/location metadata (uid, index, paneIndex, axisIndex), display metadata (title), and plot-specific state.
• The curves shape matches taxonomy defaults (getTaxonomy) and studies.lst.json.

Delete

Removes one or more plots.

• Identify by uid (preferred) or by index (typically with type).
• Delete requests are coalesced and executed in one batch.
• After deletion, plot indexes can shift. Refresh plot data with Get before using index-based calls again.

Add

Adds new plots.

• Supported add types:
  • Study (requires studyId)
  • IncomeStatement / BalanceSheet (requires fundamentalId)
  • Expression (requires expression)
  • Symbol (requires symbol)
  • Seasonal (requires seasonal)
• uid is generated by chart and cannot be supplied.
• Symbol / Expression / Seasonal can target pane/axis with paneIndex and oppositeScale.
• Seasonal defaults to offsets: [0] when offsets are not provided.
• Study supports inputs, curves, levels, bands, basis, and placement.

Study basis options:

• Omit basis (or set basis: { kind: 'main' }) to base the study on the main plot.
• Use basis: { kind: 'seasonal', uid, offset } to base the study on a seasonal plot curve.

basis examples:

// Main basis (default)
chart.change({
    id: "Plot",
    context: {
        id: "Add",
        type: "Study",
        studyId: "MA",
        basis: { kind: "main" },
    },
});

// Non-main basis: specific seasonal plot + seasonal offset
chart.change({
    id: "Plot",
    context: {
        id: "Add",
        type: "Study",
        studyId: "MA",
        basis: {
            kind: "seasonal",
            uid: "<seasonal-plot-uid>",
            offset: 0,
        },
    },
});

Notes:

• Today, the only non-main study basis is seasonal.
• uid must reference an existing seasonal plot and offset must exist in that seasonal plot.
• Some studies cannot be based on seasonal plots; incompatible basis/plot combinations are rejected.

Study placement options:

• undefined: use study defaults (overlay or standalone)
• overlay: place on main axis
• standalone: create a new pane and axis
• withMain: main pane with a secondary axis
• clone: clone placement from existing study (cloneUid preferred; cloneIndex also supported)

Update

Updates an existing plot.

• Identify by uid (preferred), index, or main: true.
• Supports updating visibility (visible) and precision (precision).
• Supports updating inputs, expressions, symbols, forwards, seasonals, basis, placement, offsets, and curves.
• For fundamentals, supports frequency updates.
• For most plots, curve count must match existing curve count.
• fields in curve definitions are not updated and can be omitted.
• showPrevious applies to the main symbol/expression plot update path.

Main-plot curve notes:

• For OHLC and Candlestick, attributes are meaningful.
• If omitted, OHLC uses a single color.
• Candlestick defaults to OpenVsClose if not set.

Forward/seasonal notes:

• Forward offsets are in days.
• Seasonal offsets are in years.
• If a seasonal update provides N offsets and N+1 curves, the last curve is treated as average; matching counts means no average curve.
• For forward and seasonal plots, use Line style curves.

Study update notes:

• placement can move a study between overlay/standalone/withMain/clone placements.
• detachedScale: true enables detached scale for the study.

For details on curve.zones, levels, and bands, see Study taxonomy.