# Widget methods

## Overview

After you create a widget with [Widget Constructor](https://charting-library-docs.xstaging.tv/latest/configuration/Widget-Constructor.md), you can control the `widget` object using the methods defined in the `IChartingLibraryWidget` interface. This article describes the most commonly used methods. Refer to the [`IChartingLibraryWidget`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md) page to see the full list of methods.

## Advanced Charts methods

### chartReady

The [`chartReady`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#chartready) method returns a promise that resolves when all data is loaded and the widget is ready. Therefore, you should call other widget methods only after this promise resolves.

```javascript
const widget = new TradingView.widget(/* Widget properties */);

widget.chartReady().then(function() {
    widget.getChartLanguage();
});
```

:::warning

The [`onChartReady(callback)`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#onchartready) overload is deprecated. Use `chartReady()` instead.

:::

### chart

The [`chart`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#chart) method returns an instance of the [`IChartWidgetApi`](../api/interfaces/Charting_Library.IChartWidgetApi.md) interface that provides an extensive API for controlling the specific chart.
For example, you can handle chart events, create indicators and drawings, change chart properties on the fly, and more. Consider the code sample below that adds the Bollinger Bands [indicator](https://charting-library-docs.xstaging.tv/latest/ui_elements/indicators.md) at the launch.

```javascript
widget.chartReady().then(() => {
    const chart = widget.chart();
    chart.createStudy(
      "Bollinger Bands", // Indicator's name
      true,              // forceOverlay
      false,             // lock
      {
        in_0: 25,        // length
        in_1: 1,         // 'mult' indicator setting
      }
    );
});
```

The `chart` method has an optional `index` parameter. If you want to interact with a certain chart on the multiple-chart layout, you should call the `chart` method with the corresponding index as a parameter.

### activeChart

The [`activeChart`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#activechart) method retrieves [`IChartWidgetApi`](../api/interfaces/Charting_Library.IChartWidgetApi.md) to interact with the currently selected chart. For example, the code sample below draws a vertical line on the chart.

```javascript
widget.activeChart().createMultipointShape(
  [{ price: 168, time: Date.UTC(2017, 10, 13) / 1000 }],
  { shape: 'vertical_line'}
);
```

You can also subscribe to events on the active chart, such as [`onIntervalChanged`](../api/interfaces/Charting_Library.IChartWidgetApi.md#onintervalchanged).

```javascript
widget.activeChart().onIntervalChanged().subscribe(null, (interval, timeframeObj) =>
    timeframeObj.timeframe = {
        value: "12M",
        type: "period-back"
});
```

Note that the library does not manage the event subscriptions when users switch between the charts on the [multiple-chart layout](https://charting-library-docs.xstaging.tv/latest/trading_terminal.md#multiple-chart-layout).
If necessary, you should manually unsubscribe from the previous chart and subscribe to the newly selected one using the corresponding [methods](https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.ISubscription). To track the currently active chart, use the [`activeChartChanged`](../api/interfaces/Charting_Library.SubscribeEventsMap.md#activechartchanged) event.

You can also find out the active chart's index using the [`activeChartIndex`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#activechartindex) method and subscribe to this chart using the [`chart`](#chart) method.

```javascript
const index = widget.activeChartIndex();
const chart = widget.chart(index);
```

### subscribe / unsubscribe

To listen to widget 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.

For example, the code sample below handles an event when an indicator is added to the chart and prints the indicator's name to the console.

```javascript
widget.subscribe('study', (event) => { console.log(`A ${event.value} indicator was added`) });
```

For specific chart events (like symbol changes, data loading, or visible range updates), refer to the [Events and subscriptions] article.

### applyOverrides

The [`applyOverrides`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#applyoverrides) method allows you to change [Overrides](https://charting-library-docs.xstaging.tv/latest/customization/overrides.md) on the fly. The code sample below hides the main [series](https://charting-library-docs.xstaging.tv/latest/resources/glossary.md#series).

```js
widget.applyOverrides({ "mainSeriesProperties.visible": false });
```

To apply overrides to a specific chart in a [multiple-chart layout](https://charting-library-docs.xstaging.tv/latest/trading_terminal.md#multiple-chart-layout), access the chart by its index:

```js
widget.chart(0).applyOverrides({ "mainSeriesProperties.visible": false });
```

### applyStudiesOverrides

The [`applyStudiesOverrides`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#applystudiesoverrides) method allows you to change [Overrides](https://charting-library-docs.xstaging.tv/latest/customization/overrides/indicator-overrides.md) that affect [indicators](https://charting-library-docs.xstaging.tv/latest/ui_elements/indicators.md) (studies) on the fly. The code sample below changes the color of the Bollinger Bands indicator.

```js
widget.applyStudiesOverrides({
    'bollinger bands.median.color': '#33FF88'
});
```

Note that this method only changes the indicator's properties before the indicator is created. You should use the [`applyOverrides`](../api/interfaces/Charting_Library.IStudyApi.md#applyoverrides) method in [`IStudyApi`](../api/interfaces/Charting_Library.IStudyApi.md) to change an indicator that is already on the chart.

### setSymbol

:::warning

`widget.setSymbol()` is deprecated. Use [`widget.activeChart().setSymbol()`](../api/interfaces/Charting_Library.IChartWidgetApi.md#setsymbol) instead.

:::

The [`setSymbol`](../api/interfaces/Charting_Library.IChartWidgetApi.md#setsymbol) method on [`activeChart`](#activechart) sets the symbol of the active chart and returns a promise that resolves when the new data has loaded.

```javascript
widget.activeChart().setSymbol('IBM');
```

### changeTheme

The [`changeTheme`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#changetheme) method allows you to change the [theme](https://charting-library-docs.xstaging.tv/latest/customization/theme.md) on the fly. This method returns a promise that is resolved once the theme is applied. You can apply other style modifications after the promise is fulfilled.

```javascript
widget.changeTheme('Dark').then(() => {
    widget.chart().applyOverrides({ 'paneProperties.backgroundGradientStartColor': 'red' });
});
```

### onShortcut

The [`onShortcut`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#onshortcut) method allows you to override the built‑in [shortcuts](https://charting-library-docs.xstaging.tv/latest/configuration/Shortcuts.md) or specify custom ones. For example, the code sample below specifies a shortcut that opens [_Symbol Search_](https://charting-library-docs.xstaging.tv/latest/ui_elements/Symbol-Search.md).

```javascript
// alt + q
widget.onShortcut(["alt", 81], function() {
    widget.chart().executeActionById("symbolSearch");
});
```

Refer to the [Manage shortcuts](https://charting-library-docs.xstaging.tv/latest/configuration/Shortcuts.md#manage-shortcuts) section for more examples.

### takeClientScreenshot

The [`takeClientScreenshot`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#takeclientscreenshot) method creates a snapshot of the chart and returns it as a canvas. You can then take the canvas element and create an image from it. The code sample below saves a screenshot as PNG.

```javascript
async function saveChartToPNG() {
  const screenshotCanvas = await widget.takeClientScreenshot();
  const linkElement = document.createElement('a');
  linkElement.download = 'screenshot';
  linkElement.href = screenshotCanvas.toDataURL(); // Alternatively, use `toBlob` which is a better API
  linkElement.dataset.downloadurl = ['image/png', linkElement.download, linkElement.href].join(':');
  document.body.appendChild(linkElement);
  linkElement.click();
  document.body.removeChild(linkElement);
}
saveChartToPNG(); // Call the screenshot function
```

### customThemes

The [`customThemes`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#customthemes) method retrieves [`ICustomThemesApi`](../api/interfaces/Charting_Library.ICustomThemesApi.md) that allows you to manage [custom themes](https://charting-library-docs.xstaging.tv/latest/customization/styles/custom-themes.md). For example, you can reset the applied themes to the default values.

```javascript
let customThemesAPI = (await widget.customThemes());
customThemesAPI.resetCustomThemes();
```

### closePopupsAndDialogs

The [`closePopupsAndDialogs`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#closepopupsanddialogs) method closes any active dialog or [context menu](https://charting-library-docs.xstaging.tv/latest/ui_elements/context-menu.md) on the chart.

```js
widget.closePopupsAndDialogs();
```

## Trading Platform methods

The methods below are available in [Trading Platform](https://charting-library-docs.xstaging.tv/latest/trading_terminal.md) only.

### widgetbar

The [`widgetbar`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#widgetbar) method retrieves [`IWidgetbarApi`](../api/interfaces/Charting_Library.IWidgetbarApi.md) that allows you to interact with the widget bar.

```javascript
widget.chartReady().then(() => {
    widget.widgetbar().then(widgetbarApi => {
       widgetbarApi.isPageVisible('data_window');
    });
});
```

### watchList

The [`watchList`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#watchlist) method retrieves [`IWatchListApi`](../api/interfaces/Charting_Library.IWatchListApi.md) that allows you to interact with the [Watchlist](https://charting-library-docs.xstaging.tv/latest/trading_terminal/Watch-List.md) widget.

```javascript
const watchlistApi = await widget.watchList();
const activeListId = watchlistApi.getActiveListId();
const currentListItems = watchlistApi.getList(activeListId);
// Adds a new section and item to the current Watchlist
watchlistApi.updateList(activeListId, [...currentListItems, '###NEW SECTION', 'AMZN']);
```

### news

The [`news`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#news) method retrieves [`INewsApi`](../api/interfaces/Charting_Library.INewsApi.md) that allows you to interact with the [News](https://charting-library-docs.xstaging.tv/latest/trading_terminal/news.md) widget.

```javascript
widget.chartReady().then(() => {
    widget.news().then(newsApi => {
        // newsApi is ready to use
    });
});
```

### chartsCount

The [`chartsCount`](../api/interfaces/Charting_Library.IChartingLibraryWidget.md#chartscount) method counts a number of charts on the multiple-chart layout. In the code sample below, this method is used to interact with all the charts on the layout one by one.

```javascript
for (let i = 0; i < widget.chartsCount(); i++) { console.log(widget.chart(i).symbolExt().name) }
```

[Events and subscriptions]: https://charting-library-docs.xstaging.tv/latest/configuration/events-and-subscriptions.md
[`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)