Events and subscriptions

Overview

The library provides an event system that allows you to react to user interactions, data updates, and layout changes. The events are grouped into three categories based on their scope:

• Widget events cover general UI interactions, layout changes, and lifecycle events affecting the entire chart layout rather than a specific chart. These are handled via widget.subscribe().
• Chart events cover changes specific to the data or state of a single chart pane. These are handled via specific methods on the IChartWidgetApi interface.
• Component events cover changes within specific components, such as watchlists or time zones.

Widget events

Widget events relate to the overall widget instance and UI elements (toolbars, dialogs, and panels). To listen to these events, use the subscribe method on the widget instance. To stop listening, use unsubscribe.

The complete list of available event names and their callback signatures is defined in the SubscribeEventsMap interface.

const widget = new TradingView.widget({ /* options */ });

widget.onChartReady(() => {
    // Subscribe to layout changes
    widget.subscribe("layout_changed", () => {
        console.log("The chart layout has been changed");
    });
});

Chart events

Events related to the chart's data, symbol, resolution, or visible range are accessible through the IChartWidgetApi. The following methods return an ISubscription object, which exposes its own subscribe and unsubscribe methods.

Method	Description
onDataLoaded	Fired when new data (history bars) is loaded for the chart.
onSymbolChanged	Fired when the chart symbol is changed.
onIntervalChanged	Fired when the chart resolution (interval) is changed. This also tracks changes to the time frame (range).
onVisibleRangeChanged	Fired when the visible time range changes.
onChartTypeChanged	Fired when the chart style (e.g., Candles, Line, Area) is changed.
crossHairMoved	Fired whenever the crosshair position updates. Provides time, price, and other coordinate data.
onHoveredSourceChanged	Fired when the user hovers the cursor over an indicator or series. Provides the ID of the source.

Since a widget can contain multiple charts (in a multiple-chart layout), you must first access the specific chart instance.

const widget = new TradingView.widget({ /* options */ });

widget.onChartReady(() => {
    const chart = widget.activeChart();

    // Subscribe to symbol change
    chart.onSymbolChanged().subscribe(null, (symbolInfo) => {
        console.log("Symbol changed to:", symbolInfo.name);
    });
});

Component events

Specific components have their own event systems that follow the ISubscription pattern. Refer to the following interfaces for more details:

• IWatchListApi for managing watchlists.
• ITimezoneApi for managing time zones.