# 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**](#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**](#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**](#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.

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

widget.chartReady().then(() => {
    // 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.

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

widget.chartReady().then(() => {
    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].

[`IWatchListApi`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IWatchListApi
[`ITimezoneApi`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.ITimezoneApi
[time zones]: https://charting-library-docs.xstaging.tv/latest/ui_elements/timezones.md
[watchlists]: https://charting-library-docs.xstaging.tv/latest/trading_terminal/Watch-List.md

[multiple-chart layout]: https://charting-library-docs.xstaging.tv/latest/trading_terminal.md#multiple-chart-layout

[`crossHairMoved`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#crosshairmoved
[`IChartWidgetApi`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi
[`ISubscription`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.ISubscription

[`onDataLoaded`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#ondataloaded
[`onSymbolChanged`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#onsymbolchanged
[`onIntervalChanged`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#onintervalchanged
[`onVisibleRangeChanged`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#onvisiblerangechanged
[`onChartTypeChanged`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#oncharttypechanged
[`onHoveredSourceChanged`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#onhoveredsourcechanged
[`subscribe`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartingLibraryWidget#subscribe
[`SubscribeEventsMap`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.SubscribeEventsMap
[`unsubscribe`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartingLibraryWidget#unsubscribe

---

## Sitemap

- [All documentation pages](https://charting-library-docs.xstaging.tv/llms.txt)
- [Full page map with headings](https://charting-library-docs.xstaging.tv/docs_map.md)