Interface: IChartingLibraryWidget

Charting Library.IChartingLibraryWidget

The main interface for interacting with the library, returned by ChartingLibraryWidgetConstructor. For more information, refer to the Widget methods article.

Methods

activeChart

▸ activeChart(): IChartWidgetApi

Get an API object for interacting with the active chart.

Returns

IChartWidgetApi

An API object for interacting with the chart.

---

activeChartIndex

▸ activeChartIndex(): number

Get the index of the active chart in the layout.

Returns

number

number.

---

addCustomCSSFile

▸ addCustomCSSFile(url): void

Add a custom CSS file for the library to load.

Parameters

Name	Type	Description
url	string	A url to the custom CSS file. Should be absolute or relative to the static folder.

Returns

void

---

applyOverrides

▸ applyOverrides<TOverrides>(overrides): void

Apply overrides to the chart without reloading. See also ChartingLibraryWidgetOptions.overrides.

Type parameters

Name	Type
TOverrides	extends Partial<ChartPropertiesOverrides>

Parameters

Name	Type	Description
overrides	TOverrides	An object of overrides to apply to the chart.

Returns

void

---

applyStudiesOverrides

▸ applyStudiesOverrides(overrides): void

Apply overrides to indicator styles and inputs without reloading. Refer to Indicator Overrides for more information. Overrides for built-in indicators are listed in StudyOverrides.

Parameters

Name	Type	Description
overrides	object	An object of overrides to apply to the studies.

Returns

void

---

changeTheme

▸ changeTheme(themeName, options?): Promise<void>

Change the theme of the chart.

Parameters

Name	Type	Description
themeName	ThemeName	A theme name.
options?	ChangeThemeOptions	An optional object of options for the theme.

Returns

Promise<void>

A promise that resolves when the theme has been changed.

---

chart

▸ chart(index?): IChartWidgetApi

Get an API instance that can be used to interact with a chart.

Parameters

Name	Type	Description
index?	number	Zero based index of the chart.

Returns

IChartWidgetApi

An API instance.

---

chartsCount

▸ chartsCount(): number

Get the number of charts in the current layout.

Returns

number

A count of the charts in the current layout.

---

clearUndoHistory

▸ clearUndoHistory(): void

Clears the undo & redo history.

Warning: this should only be used in very specific cases where you have considered the UX implications. It is generally unexpected for the user that the undo history has been cleared.

An example of an acceptable use-case would be reusing a chart when switching pages / tabs on a Single Page Application, and presenting it to the user as a new chart.

Returns

void

---

closePopupsAndDialogs

▸ closePopupsAndDialogs(): void

Close all open context menus, pop-ups or dialogs.

Returns

void

---

createButton

▸ createButton(options?): HTMLElement

Create a button in the top toolbar. This should be called after headerReady has resolved.

Example

widget.headerReady().then(function() {
    var button = widget.createButton();
    button.setAttribute('title', 'My custom button tooltip');
    button.addEventListener('click', function() { alert("My custom button pressed!"); });
    button.textContent = 'My custom button caption';
});

Parameters

Name	Type	Description
options?	CreateHTMLButtonOptions	A optional object of options for the button.

Returns

HTMLElement

A HTMLElement you can customize.

▸ createButton(options?): void

Create a button in the top toolbar. This should be called after headerReady has resolved. If the title option is provided then the title text will be shown in a tooltip on hover. If the onClick option is provided then the button will be clickable.

Parameters

Name	Type	Description
options?	CreateTradingViewStyledButtonOptions	A optional object of options for the button.

Returns

void

▸ createButton(options?): HTMLElement

Create a button in the top toolbar. This should be called after headerReady has resolved.

Parameters

Name	Type	Description
options?	CreateButtonOptions	A optional object of options for the button.

Returns

HTMLElement

A HTMLElement if the useTradingViewStyle option if false. undefined if useTradingViewStyle is true.

---

createDropdown

▸ createDropdown(params): Promise<IDropdownApi>

Add a custom dropdown menu to the top toolbar.

Example

widget.createDropdown(
    {
        title: 'dropdown',
        tooltip: 'tooltip for this dropdown',
        items: [
            {
                title: 'item#1',
                onSelect: () => {console.log('1');},
            },
            {
                title: 'item#2',
                onSelect: () => {widget.setSymbol('IBM', '1D');},
            },
            {
                title: 'item#3',
                onSelect: () => {
                    widget.activeChart().createStudy(
                        'MACD',
                        false,
                        false,
                        {
                            in_0: 14,
                            in_1: 30,
                            in_3: 'close',
                            in_2: 9
                        }
                    );
                },
            }
        ],
        icon: `<svg xmlns="http://www.w3.org/2000/svg" width="28" height="28"><g fill="none" stroke="currentColor"><circle cx="10" cy="10" r="2.5"/><circle cx="18" cy="18" r="2.5"/><path stroke-linecap="square" d="M17.5 7.5l-7 13"/></g></svg>`,
    }
).then(myDropdownApi => {
    // Use myDropdownApi if you need to update the dropdown:
    // myDropdownApi.applyOptions({
    //     title: 'a new title!'
    // });

    // Or remove the dropdown:
    // myDropdownApi.remove();
});

Parameters

Name	Type
params	DropdownParams

Returns

Promise<IDropdownApi>

---

crosshairSync

▸ crosshairSync(): IWatchedValue<boolean>

Only available in Trading Platform. Get a watched value that can be used to read/write/subscribe to the state of the crosshair sync between charts.

Example

widget.crosshairSync().setValue(true);

Returns

IWatchedValue<boolean>

A watched value of the state of the crosshair sync.

---

currencyAndUnitVisibility

▸ currencyAndUnitVisibility(): IWatchedValue<VisibilityType>

Get a watched value that can be used to read/write/subscribe to the state of the currency and unit visibility setting on the price scale.

Returns

IWatchedValue<VisibilityType>

A watched value of the state of the currency and unit visibility option.

---

customSymbolStatus

▸ customSymbolStatus(): ICustomSymbolStatusApi

Get an API object for creating, and adjusting, custom status items to be displayed within the legend for the main series of each chart.

This can only be accessed when the chart has been created. (headerReady)

Returns

ICustomSymbolStatusApi

An API object for controlling additional custom status items within the legend area.

---

dateFormat

▸ dateFormat(): IWatchedValue<"dd MMM 'yy" | "MMM dd, yyyy" | "MMM yyyy" | "MMM dd" | "dd MMM" | "yyyy-MM-dd" | "yy-MM-dd" | "yy/MM/dd" | "yyyy/MM/dd" | "dd-MM-yyyy" | "dd-MM-yy" | "dd/MM/yy" | "dd/MM/yyyy" | "MM/dd/yy" | "MM/dd/yyyy">

Get a watched value that can be used to read/write/subscribe to the state of the date format.

Returns

IWatchedValue<"dd MMM 'yy" | "MMM dd, yyyy" | "MMM yyyy" | "MMM dd" | "dd MMM" | "yyyy-MM-dd" | "yy-MM-dd" | "yy/MM/dd" | "yyyy/MM/dd" | "dd-MM-yyyy" | "dd-MM-yy" | "dd/MM/yy" | "dd/MM/yyyy" | "MM/dd/yy" | "MM/dd/yyyy">

A watched value of the state of the date format.

---

dateRangeSync

▸ dateRangeSync(): IWatchedValue<boolean>

Only available in Trading Platform. Get a watched value that can be used to read/write/subscribe to the state of the date range sync between charts.

Example

widget.dateRangeSync().setValue(true);

Returns

IWatchedValue<boolean>

A watched value of the state of the date range sync.

---

exitFullscreen

▸ exitFullscreen(): void

Set the chart into non-fullscreen mode (if it isn't already).

Returns

void

---

getCSSCustomPropertyValue

▸ getCSSCustomPropertyValue(customPropertyName): string

Returns the current value for a CSS custom property.

Example:

const currentValue = widget.getCSSCustomPropertyValue('--my-theme-color');

Parameters

Name	Type	Description
customPropertyName	string	A string representing the CSS custom property name to be checked. It is expected that the name should start with a double hyphen ('--').

Returns

string

A string containing the value of the property. If not set, returns the empty string.

---

getIntervals

▸ getIntervals(): string[]

Get an array of supported intervals (resolutions).

Returns

string[]

An array of supported intervals. E.g. ['1D', '5D', '1Y'].

---

getLanguage

▸ getLanguage(): LanguageCode

Get the configured locale of the widget. For example en, zh, ru.

Returns

LanguageCode

A code representing the locale of the widget.

---

getSavedCharts

▸ getSavedCharts(callback): void

Get a list of chart descriptions saved to the server for the current user.

Parameters

Name	Type	Description
callback	(chartRecords: SaveLoadChartRecord[]) => void	A function called with an array of saved chart information as the first argument.

Returns

void

---

getStudiesList

▸ getStudiesList(): string[]

Get an array of the names of all supported studies. These names can be used when calling IChartWidgetApi.createStudy.

Returns

string[]

An array of supported study names. E.g. ['Accumulation/Distribution', 'Accumulative Swing Index', 'Advance/Decline', ...].

---

getStudyInputs

▸ getStudyInputs(studyName): StudyInputInformation[]

Get an array of information about the inputs of a study.

Parameters

Name	Type	Description
studyName	string	The name of a study.

Returns

StudyInputInformation[]

---

getStudyStyles

▸ getStudyStyles(studyName): StudyStyleInfo

Get information about the styles of a study.

Parameters

Name	Type	Description
studyName	string	The name of a study.

Returns

StudyStyleInfo

---

getTheme

▸ getTheme(): ThemeName

Get the current theme of the chart.

Example

console.log(widget.getTheme());

Returns

ThemeName

A theme name. The name of the current theme.

---

headerReady

▸ headerReady(): Promise<void>

A promise that resolves if and when the header is ready to be used.

Returns

Promise<void>

---

hideAllDrawingTools

▸ hideAllDrawingTools(): IWatchedValue<boolean>

Get a watched value that can be used to read/write/subscribe to the state of the "Hide All Drawing Tools" button.

Returns

IWatchedValue<boolean>

A watched value of the state of the "Hide All Drawing Tools" button.

---

intervalSync

▸ intervalSync(): IWatchedValue<boolean>

Only available in Trading Platform. Get a watched value that can be used to read/write/subscribe to the state of the interval sync between charts.

Example

widget.intervalSync().setValue(true);

Returns

IWatchedValue<boolean>

A watched value of the state of the interval sync.

---

layout

▸ layout(): LayoutType

Get the current chart layout type.

Returns

LayoutType

A string representation of the current layout type. E.g. '2h' for two charts split vertically.

---

layoutName

▸ layoutName(): string

Get the name of the current chart layout. The return value will be undefined if the current layout has not been saved.

Returns

string

A string of the name of the current chart layout.

---

load

▸ load(state, extendedData?): void

Loads the chart state from a object. This method is part of the low-level save/load API.

Parameters

Name	Type	Description
state	object	A chart state object to load.
extendedData?	SavedStateMetaInfo	A optional object of information about the saved state.

Returns

void

---

loadChartFromServer

▸ loadChartFromServer(chartRecord): void

Load a saved chart from the server.

Parameters

Name	Type	Description
chartRecord	SaveLoadChartRecord	A chart information object (returned by getSavedCharts).

Returns

void

---

lockAllDrawingTools

▸ lockAllDrawingTools(): IWatchedValue<boolean>

Get a watched value that can be used to read/write/subscribe to the state of the "Lock All Drawing Tools" button.

Returns

IWatchedValue<boolean>

A watched value of the state of the "Lock All Drawing Tools" button.

---

magnetEnabled

▸ magnetEnabled(): IWatchedValue<boolean>

Get a watched value that can be used to read/write/subscribe to the state of the magnet.

Returns

IWatchedValue<boolean>

A watched value of the state of the magnet.

---

magnetMode

▸ magnetMode(): IWatchedValue<number>

Get a watched value that can be used to read/write/subscribe to the state of the magnet mode.

Returns

IWatchedValue<number>

A watched value of the state of the magnet mode.

---

mainSeriesPriceFormatter

▸ mainSeriesPriceFormatter(): INumberFormatter

Get the price formatter for the main series. You can use this to format prices as the char

Returns

INumberFormatter

---

navigationButtonsVisibility

▸ navigationButtonsVisibility(): IWatchedValue<VisibilityType>

Get a watched value that can be used to read/write/subscribe to the state of the navigation buttons.

Returns

IWatchedValue<VisibilityType>

A watched value of the state of the navigation buttons.

---

news

▸ news(): Promise<INewsApi>

Trading Platform only. Get a promise that resolves with an API object for interacting with the widgetbar (right sidebar) news widget.

Returns

Promise<INewsApi>

An API object for interacting with the widgetbar (right sidebar) widget.

---

onChartReady

▸ onChartReady(callback): void

The library will call callback when the chart is ready to be used.

Parameters

Name	Type	Description
callback	EmptyCallback	A function that will be called when the chart is ready to be used.

Returns

void

---

onContextMenu

▸ onContextMenu(callback): void

The widget will call the callback function each time the widget wants to display a context menu. See also ChartingLibraryWidgetOptions.context_menu.

Example

widget.onChartReady(function() {
    widget.onContextMenu(function(unixtime, price) {
        return [{
            position: "top",
            text: "First top menu item, time: " + unixtime + ", price: " + price,
            click: function() { alert("First clicked."); }
        },
        { text: "-", position: "top" }, // Adds a separator between buttons
        { text: "-Paste" },             // Removes the existing item from the menu
        {
            position: "top",
            text: "Second top menu item 2",
            click: function() { alert("Second clicked."); }
        }, {
            position: "bottom",
            text: "Bottom menu item",
            click: function() { alert("Third clicked."); }
        }];
    });
});

Parameters

Name	Type	Description
callback	(unixTime: number, price: number) => ContextMenuItem[]	A function called with the time and price of the location on the chart that triggered the context menu. The array of objects returned will add or remove items from the context menu.

Returns

void

---

onGrayedObjectClicked

▸ onGrayedObjectClicked(callback): void

The library will call callback when a greyed-out drawing tool or study is clicked.

Parameters

Name	Type	Description
callback	(obj: GrayedObject) => void	A function that will be called when a greyed-out drawing tool or study is clicked.

Returns

void

---

onShortcut

▸ onShortcut(shortCut, callback): void

The library will call callback when the shortCut keys are input.

Use a string separated by '+' for shortcuts using an alphabet character (A to Z) with optional modifiers (ctrl, shift, alt). Use a number for shortcuts using non-alphabet character without modifiers. If you don't know the key code you need you can use resources like keycode.info, or MDN to check. Use an array of literal key codes and modifier strings for shortcuts using non-alphabet characters with optional modifier strings.

Parameters

Name	Type	Description
shortCut	string | number | (string | number)[]	A number, a string, or an array of number and string.
callback	EmptyCallback	A function that will be called when the shortCut keys are input.

Returns

void

Example

widget.onShortcut("alt+q", function() {
  widget.chart().executeActionById("symbolSearch");
});

// F1
widget.onShortcut(112, function() {
  widget.chart().executeActionById("symbolSearch");
});

// ctrl+shift+\
widget.onShortcut(['ctrl', 'shift', 220], function() {
	 widget.chart().executeActionById("symbolSearch");
});

---

paneButtonsVisibility

▸ paneButtonsVisibility(): IWatchedValue<VisibilityType>

Get a watched value that can be used to read/write/subscribe to the state of the pane buttons.

Returns

IWatchedValue<VisibilityType>

A watched value of the state of the pane buttons.

---

remove

▸ remove(): void

Remove the widget and all its data from the page. The widget cannot be interacted with after it has been removed.

Returns

void

---

removeChartFromServer

▸ removeChartFromServer(chartId, onCompleteCallback): void

Remove a saved chart from the server.

Parameters

Name	Type	Description
chartId	string	A chart ID from a SaveLoadChartRecord (returned by getSavedCharts).
onCompleteCallback	EmptyCallback	A callback function called when the chart is successfully saved.

Returns

void

---

save

▸ save(callback): void

Saves the chart state to a object. This method is part of the low-level save/load API.

Parameters

Name	Type	Description
callback	(state: object) => void	A function called with the chart state as the first argument.

Returns

void

---

saveChartToServer

▸ saveChartToServer(onComplete?, onFail?, options?): void

Save the current chart to the server.

Parameters

Name	Type	Description
onComplete?	EmptyCallback	An optional callback function called when the chart is successfully saved.
onFail?	EmptyCallback	An optional callback function called when the chart fails to save.
options?	SaveChartToServerOptions	An optional object of options for saving the chart.

Returns

void

---

selectLineTool

▸ selectLineTool(linetool, options?): void

Select an icon. It's the same as clicking on the corresponding button in the left toolbar.

Parameters

Name	Type	Description
linetool	"icon"	An icon drawing tool.
options?	IconOptions	An optional object with options.

Returns

void

▸ selectLineTool(linetool): void

Select a drawing or a cursor. It's the same as clicking on the corresponding button in the left toolbar.

Parameters

Name	Type	Description
linetool	Omit<"icon", SupportedLineTools>	A drawing or cursor to select (excluding 'icon')

Returns

void

▸ selectLineTool(linetool, options?): void

Select the Icon line tool. It's the same as clicking on the corresponding button in the left toolbar.

Parameters

Name	Type	Description
linetool	"icon"	Icon line tool.
options?	IconOptions	An optional object with options. Currently only used for the 'icon' drawing.

Returns

void

▸ selectLineTool(linetool, options?): void

Select the Emoji line tool. It's the same as clicking on the corresponding button in the left toolbar.

Parameters

Name	Type	Description
linetool	"emoji"	Emoji line tool.
options?	EmojiOptions	Options for the Emoji line tool

Returns

void

▸ selectLineTool(linetool, options?): void

Select a drawing, icon, or a cursor. It's the same as clicking on the corresponding button in the left toolbar.

Parameters

Name	Type	Description
linetool	SupportedLineTools	A drawing or cursor to select.
options?	EmojiOptions | IconOptions	An optional object with options.

Returns

void

---

selectedLineTool

▸ selectedLineTool(): SupportedLineTools

Get the currently selected drawing or cursor.

Returns

SupportedLineTools

An identifier for drawing or cursor.

---

setActiveChart

▸ setActiveChart(index): void

Set which chart is currently active. It is recommended that this method is only used when linked to a user action which should change the active chart.

Use chartsCount to determine the number of charts currently available. If an invalid index is supplied (less than zero, or greater than the number of charts minus 1) then this method will not change the active chart.

Parameters

Name	Type	Description
index	number	index of chart to set as the active chart. Index is zero-based.

Returns

void

---

setCSSCustomProperty

▸ setCSSCustomProperty(customPropertyName, value): void

Sets the value for a CSS custom property.

Example:

widget.setCSSCustomProperty('--my-theme-color', '#123AAA');

Parameters

Name	Type	Description
customPropertyName	string	A string representing the CSS custom property name. It is expected that the name should start with a double hyphen ('--').
value	string	A string containing the new property value.

Returns

void

---

setDebugMode

▸ setDebugMode(enabled): void

Enable or disable debug mode.

Parameters

Name	Type	Description
enabled	boolean	A boolean flag. true to enable debug mode, false to disable.

Returns

void

---

setLayout

▸ setLayout(layout): void

Set the current chart layout type.

Parameters

Name	Type
layout	LayoutType

Returns

void

Params

layout A string representation of the new layout type. E.g. '2h' for two charts split vertically.

---

setSymbol

▸ setSymbol(symbol, interval, callback): void

Set the symbol and resolution of the active chart.

Parameters

Name	Type	Description
symbol	string	A symbol to load.
interval	ResolutionString	A interval (resolution) to load.
callback	EmptyCallback	A callback. Called when the symbol's data has finished loading.

Returns

void

---

showConfirmDialog

▸ showConfirmDialog(params): void

Show a dialog with custom title and text along with "OK" and "CANCEL" buttons.

Parameters

Name	Type	Description
params	DialogParams<(confirmed: boolean) => void>	A object of options for the created dialog.

Returns

void

---

showLoadChartDialog

▸ showLoadChartDialog(): void

Show the "Load Chart Layout" dialog.

Returns

void

---

showNoticeDialog

▸ showNoticeDialog(params): void

Show a dialog with custom title and text along with an "OK" buttons.

Parameters

Name	Type	Description
params	DialogParams<() => void>	A object of options for the created dialog.

Returns

void

---

showSaveAsChartDialog

▸ showSaveAsChartDialog(): void

Show the "Copy Chart Layout" dialog.

Returns

void

---

startFullscreen

▸ startFullscreen(): void

Set the chart into fullscreen mode (if it isn't already).

Returns

void

---

subscribe

▸ subscribe<EventName>(event, callback): void

Subscribe to library events.

Type parameters

Name	Type
EventName	extends keyof SubscribeEventsMap

Parameters

Name	Type	Description
event	EventName	A event to subscribe to.
callback	SubscribeEventsMap[EventName]	A callback that will be called when the event happens.

Returns

void

---

supportedChartTypes

▸ supportedChartTypes(): IWatchedValueReadonly<ChartStyle[]>

This method returns a readonly WatchedValue (IWatchedValueReadonly) object that can be used to read/watch the current supported chart types (SeriesType) for an active chart.

The chart type is returned as a number. You can see which number corresponds to which chart type in the Overrides documentation for mainSeriesProperties.style.

Returns

IWatchedValueReadonly<ChartStyle[]>

---

symbolInterval

▸ symbolInterval(): SymbolIntervalResult

Get the symbol and interval of the active chart.

Returns

SymbolIntervalResult

---

symbolSync

▸ symbolSync(): IWatchedValue<boolean>

Only available in Trading Platform. Get a watched value that can be used to read/write/subscribe to the state of the symbol sync between charts.

Example

if (widget.symbolSync().value()) {
    // ...
}

Returns

IWatchedValue<boolean>

A watched value of the state of the symbol sync.

---

takeClientScreenshot

▸ takeClientScreenshot(options?): Promise<HTMLCanvasElement>

Create a snapshot of the chart and return it as a canvas.

Parameters

Name	Type	Description
options?	Partial<ClientSnapshotOptions>	An optional object that customizes the returned snapshot.

Returns

Promise<HTMLCanvasElement>

A promise containing a HTMLCanvasElement of the snapshot.

---

takeScreenshot

▸ takeScreenshot(): void

Create a snapshot of the chart and upload it to the server. When it is ready callback functions subscribed to the 'onScreenshotReady' event using subscribe will be called. The URL of the snapshot will be passed as an argument to the callback function.

Returns

void

---

timeHoursFormat

▸ timeHoursFormat(): IWatchedValue<TimeHoursFormat>

Get a watched value that can be used to read/write/subscribe to the state of the timeHours format.

Returns

IWatchedValue<TimeHoursFormat>

---

timeSync

▸ timeSync(): IWatchedValue<boolean>

Only available in Trading Platform. Get a watched value that can be used to read/write/subscribe to the state of the time sync between charts.

Example

widget.timeSync().setValue(true);

Returns

IWatchedValue<boolean>

A watched value of the state of the time sync.

---

undoRedoState

▸ undoRedoState(): UndoRedoState

Get the state of the undo/redo stack.

Returns

UndoRedoState

---

unsubscribe

▸ unsubscribe<EventName>(event, callback): void

Unsubscribe from library events.

Type parameters

Name	Type
EventName	extends keyof SubscribeEventsMap

Parameters

Name	Type	Description
event	EventName	A event to unsubscribe from.
callback	SubscribeEventsMap[EventName]	A callback to unsubscribe. Must be the same reference as a callback passed to subscribe.

Returns

void

---

watchList

▸ watchList(): Promise<IWatchListApi>

Trading Platform only. Get a promise that resolves with an API object for interacting with the widgetbar (right sidebar) watchlist.

Example

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

Returns

Promise<IWatchListApi>

An API object for interacting with the widgetbar (right sidebar) watchlist.

---

watermark

▸ watermark(): IWatermarkApi

Get an API object for adjusting the watermarks present on the charts. This can only be accessed when the chart is ready to be used. (onChartReady)

Returns

IWatermarkApi

An API object for adjusting the watermark settings.

---

widgetbar

▸ widgetbar(): Promise<IWidgetbarApi>

Trading Platform only. Get a promise that resolves with an API object for interacting with the widgetbar (right sidebar).

Returns

Promise<IWidgetbarApi>

An API object for interacting with the widgetbar (right sidebar).