Chart Events

The SDK exposes one typed event bus. Subscribe with widget.on(type, handler) or chart.on(type, handler); both return an Unsubscribe function. Hosts that want a single stream can also pass onEvent in ChartWidgetOptions.

The event names and payloads are owned by ChartEventPayloadMap. Events are grouped below by family:

Family	Covers
Lifecycle	Readiness, layouts, templates, autosave, undo/redo, replay, customization
Data	Symbol, interval, bars, indicators, comparisons, data errors
UI	Selection, crosshair, drawings, panes, pointers, dialogs, favorites
Trading	Trading intents, markers, alerts, order flow

Subscribing and unsubscribing

Every on(...) call returns its own unsubscribe function. Keep it and call it when the subscription's owner unmounts; in React, return it from the effect that created it. widget.destroy() tears down all remaining subscriptions with the widget, so process-lifetime subscriptions need no manual cleanup.

const unsubscribe = widget.on('bar-update', (event) => {
  console.log(event.payload.symbol.ticker, event.payload.bar.close);
});

widget.on('bars-loaded', (event) => {
  console.log(event.payload.type, event.payload.barCount);
});

unsubscribe();

Event flow example

One user action typically produces a short event sequence. Changing the symbol emits symbol-change once, then bars-loaded for the initial history request, then a bar-update stream while realtime data arrives:

const offSymbol = chart.on('symbol-change', (event) => {
  console.log('now viewing', event.payload.ticker);
});
const offLoaded = chart.on('bars-loaded', (event) => {
  console.log(event.payload.type, event.payload.barCount);
});
const offBar = chart.on('bar-update', (event) => {
  console.log('close', event.payload.bar.close);
});

await chart.setSymbol('MSFT');

// Later, when the observing component goes away:
offSymbol();
offLoaded();
offBar();

Lifecycle events

Readiness, persistence, templates, history, replay, and customization state.

autosave-needed emits a debounced layout/state snapshot when ChartWidgetOptions.autoSave is enabled. Autosave reason codes include symbol, interval, drawing, indicator, comparison, display, customization, price-scale, drag-export, pane-order, and template mutations.

Event	Payload
ready	ChartState
layout-change	ChartLayout
layout-load-requested	{ layout: ChartLayout }
layout-about-to-change	{ layout: ChartLayout; reason: string }
autosave-needed	AutoSaveNeededPayload
active-chart-change	{ chartId: ChartId }
template-change	{ template?: ChartTemplate; templateId?: ChartTemplateId; deleted?: boolean; action?: 'save' | 'load' | 'delete' | 'apply' }
undo-redo-state-change	UndoRedoState
user-settings-change	UserSettingsState
replay-change	ReplayEvent
customization-change	CustomizationEvent
action-run	CustomizationEvent

Data events

Symbol, interval, series data, indicators, and data failures.

Event	Payload
symbol-change	SymbolInfo
interval-change	{ interval: ChartInterval }
chart-type-change	{ chartType: ChartType }
bar-update	{ bar: Bar; symbol: SymbolInfo; interval: ChartInterval }
bars-loaded	{ symbol: SymbolInfo; interval: ChartInterval; type: string; barCount: number }
indicator-change	{ indicator?: IndicatorDefinition; indicatorId?: string; removed?: boolean }
comparison-change	ComparisonChangeEvent
data-error	ChartError

UI events

Selection, crosshair, drawings, panes, pointers, dialogs, and favorites.

PaneLayoutPayload contains paneId for single-pane changes, paneIds for batch changes, panes, and optional raw; each pane entry exposes paneId, height, order, visible, and optional top, minHeight, and state. PaneOrderChangePayload adds previousPanes.

Properties-dialog open/close transitions emit properties-dialog-change. Other built-in dialogs (indicators, settings) and context-menu lifecycle emit dialog-state-change with the owning dialogId.

Event	Payload
object-change	ChartObjectChange discriminated union for drawings, objects, comparisons, and providers
selection-change	ChartObjectSelection
visible-range-change	VisibleBarRange | VisibleTimeRange | Record<string, unknown>
price-scale-change	PriceScaleSettings
crosshair-change	CrosshairState | undefined
display-settings-change	ChartDisplaySettings
drawings-change	DrawingSnapshot
drawing-tool-change	{ toolId?: string }
hover-object-change	{ object?: ChartObjectNode; previousObjectId?: string }
dialog-state-change	{ dialogId: string; open: boolean; metadata?: Record<string, unknown> }
pane-drag	PaneLayoutPayload
pane-drag-end	PaneLayoutPayload
pane-order-change	PaneOrderChangePayload
chart-pointer-down	ChartPointerPayload
chart-pointer-move	ChartPointerPayload
chart-pointer-up	ChartPointerPayload
chart-drag-export	ChartDragExportPayload
bar-click	{ dataIndex?: number; timestamp?: number; value?: number; raw?: unknown }
tooltip-feature-click	{ kind: 'candle' | 'indicator' | 'crosshair'; featureId?: string; indicatorId?: string; paneId?: string; raw?: unknown }
interval-favorites-change	{ favorites: string[] }
chart-type-favorites-change	{ favorites: ChartType[] }
drawing-tool-favorites-change	{ favorites: string[] }
indicator-favorites-change	{ favorites: string[] }

Trading events

Trading intents, price-axis actions, markers, alerts, and order-flow overlays.

Event	Payload
trading-intent	TradingIntentPayload
price-axis-action	PriceAxisActionEvent
markers-change	MarkerDefinition[]
marker-click	{ markerId: string; marker: MarkerDefinition; point?: MarkerPoint }
alerts-change	AlertDefinition[]
alert-trigger	AlertTriggerContext
alert-activate	{ alertId: string; alert: AlertDefinition }
orderflow-heatmap-change	{ options: OrderFlowHeatmapOptions | null }
footprint-change	{ options: FootprintChartOptions | null }

Alert events are documented in depth under Alerts.

Related pages

• Chart Controller — the operations that emit these events.
• Events API — the searchable declaration for every payload type.
• Widget Options — the onEvent option for a single combined stream.