IChartingLibraryWidget

Interface

The main interface for interacting with the library.

This interface is returned to you by the widget's constructor (ChartingLibraryWidgetConstructor).

Remark: Please note that it's safe to call any method only after onChartReady callback function is called.

Example:

widget.onChartReady(function() {
    // It's now safe to call any other methods of the widget
});

Methods

activeChart

Get an API object for interacting with the active chart.

Signature

activeChart() => IChartWidgetApi

Returns

An API object for interacting with the chart.

​IChartWidgetApi

---

activeChartIndex

Get the index of the active chart in the layout.

Signature

activeChartIndex() => number

Returns

number.

​number

---

addCustomCSSFile

Add a custom CSS file for the library to load.

Signature

addCustomCSSFile(url: string) => void

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

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

Signature

applyOverrides<TOverrides>(overrides: TOverrides) => void

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

Apply overrides to study styles and inputs without reloading. See also ChartingLibraryWidgetOptions.studies_overrides.

Signature

applyStudiesOverrides(overrides: object) => void

Parameters

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

Returns

​void

---

changeTheme

Change the theme of the chart.

Signature

changeTheme(themeName: ThemeName, options?: ChangeThemeOptions) => Promise<void>

Parameters

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

Returns

A promise that resolves when the theme has been changed.

​Promise<void>

---

chart

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

Signature

chart(index?: number) => IChartWidgetApi

Parameters

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

Returns

An API instance.

​IChartWidgetApi

---

chartsCount

Get the number of charts in the current layout.

Signature

chartsCount() => number

Returns

A count of the charts in the current layout.

​number

---

clearUndoHistory

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.

Signature

clearUndoHistory() => void

Returns

​void

---

closePopupsAndDialogs

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

Signature

closePopupsAndDialogs() => void

Returns

​void

---

createButton

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

Signature

createButton(options?: CreateHTMLButtonOptions) => HTMLElement

Parameters

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

Returns

A HTMLElement you can customize.

​HTMLElement

---

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.

Signature

createButton(options?: CreateTradingViewStyledButtonOptions) => void

Parameters

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

Returns

​void

---

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

Signature

createButton(options?: CreateButtonOptions) => HTMLElement

Parameters

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

Returns

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

​HTMLElement

---

createDropdown

add your own dropdown menu to the top toolbar.

Signature

createDropdown(params: DropdownParams) => Promise<IDropdownApi>

Parameters

Name	Type
params	DropdownParams

Returns

​Promise<IDropdownApi>

---

crosshairSync

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

Signature

crosshairSync() => IWatchedValue<boolean>

Returns

A watched value of the state of the crosshair sync.

​IWatchedValue<boolean>

---

currencyAndUnitVisibility

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.

Signature

currencyAndUnitVisibility() => IWatchedValue<VisibilityType>

Returns

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

​IWatchedValue<VisibilityType>

---

customSymbolStatus

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)

Signature

customSymbolStatus() => ICustomSymbolStatusApi

Returns

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

​ICustomSymbolStatusApi

---

dateFormat

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

Signature

dateFormat() => IWatchedValue<"dd MMM 'yy" | "MMM dd, 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">

Returns

A watched value of the state of the date format.

​IWatchedValue<"dd MMM 'yy" | "MMM dd, 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">

---

dateRangeSync

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

Signature

dateRangeSync() => IWatchedValue<boolean>

Returns

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

​IWatchedValue<boolean>

---

exitFullscreen

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

Signature

exitFullscreen() => void

Returns

​void

---

getIntervals

Get an array of supported intervals (resolutions).

Signature

getIntervals() => string[]

Returns

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

​string[]

---

getLanguage

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

Signature

getLanguage() => LanguageCode

Returns

A code representing the locale of the widget.

​LanguageCode

---

getSavedCharts

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

Signature

getSavedCharts(callback: Function) => void

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

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

Signature

getStudiesList() => string[]

Returns

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

​string[]

---

getStudyInputs

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

Signature

getStudyInputs(studyName: string) => StudyInputInformation[]

Parameters

Name	Type	Description
studyName	string	The name of a study.

Returns

​StudyInputInformation[]

---

getStudyStyles

Get information about the styles of a study.

Signature

getStudyStyles(studyName: string) => StudyStyleInfo

Parameters

Name	Type	Description
studyName	string	The name of a study.

Returns

​StudyStyleInfo

---

getTheme

Get the current theme of the chart.

Signature

getTheme() => ThemeName

Returns

A theme name. The name of the current theme.

​ThemeName

---

headerReady

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

Signature

headerReady() => Promise<void>

Returns

​Promise<void>

---

hideAllDrawingTools

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

Signature

hideAllDrawingTools() => IWatchedValue<boolean>

Returns

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

​IWatchedValue<boolean>

---

intervalSync

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

Signature

intervalSync() => IWatchedValue<boolean>

Returns

A watched value of the state of the interval sync.

​IWatchedValue<boolean>

---

layout

Get the current chart layout type.

Signature

layout() => LayoutType

Returns

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

​LayoutType

---

layoutName

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

Signature

layoutName() => string

Returns

A string of the name of the current chart layout.

​string

---

load

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

Signature

load(state: object, extendedData?: SavedStateMetaInfo) => void

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

Load a saved chart from the server.

Signature

loadChartFromServer(chartRecord: SaveLoadChartRecord) => void

Parameters

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

Returns

​void

---

lockAllDrawingTools

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

Signature

lockAllDrawingTools() => IWatchedValue<boolean>

Returns

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

​IWatchedValue<boolean>

---

magnetEnabled

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

Signature

magnetEnabled() => IWatchedValue<boolean>

Returns

A watched value of the state of the magnet.

​IWatchedValue<boolean>

---

magnetMode

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

Signature

magnetMode() => IWatchedValue<number>

Returns

A watched value of the state of the magnet mode.

​IWatchedValue<number>

---

mainSeriesPriceFormatter

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

Signature

mainSeriesPriceFormatter() => INumberFormatter

Returns

​INumberFormatter

---

navigationButtonsVisibility

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

Signature

navigationButtonsVisibility() => IWatchedValue<VisibilityType>

Returns

A watched value of the state of the navigation buttons.

​IWatchedValue<VisibilityType>

---

news

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

Signature

news() => Promise<INewsApi>

Returns

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

​Promise<INewsApi>

---

onChartReady

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

Signature

onChartReady(callback: EmptyCallback) => void

Parameters

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

Returns

​void

---

onContextMenu

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

Signature

onContextMenu(callback: Function) => void

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

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

Signature

onGrayedObjectClicked(callback: Function) => void

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

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.

Example

widget.onShortcut("alt+s", 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");
});

Signature

onShortcut(shortCut: string | number | (string | number)[], callback: EmptyCallback) => void

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

---

paneButtonsVisibility

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

Signature

paneButtonsVisibility() => IWatchedValue<VisibilityType>

Returns

A watched value of the state of the pane buttons.

​IWatchedValue<VisibilityType>

---

remove

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

Signature

remove() => void

Returns

​void

---

removeChartFromServer

Remove a saved chart from the server.

Signature

removeChartFromServer(chartId: string, onCompleteCallback: EmptyCallback) => void

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

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

Signature

save(callback: Function) => void

Parameters

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

Returns

​void

---

saveChartToServer

Save the current chart to the server.

Signature

saveChartToServer(onComplete?: EmptyCallback, onFail?: EmptyCallback, options?: SaveChartToServerOptions) => void

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

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

Signature

selectLineTool(linetool: "icon", options?: IconOptions) => void

Parameters

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

Returns

​void

---

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

Signature

selectLineTool(linetool: Omit<"icon", SupportedLineTools>) => void

Parameters

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

Returns

​void

---

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

Signature

selectLineTool(linetool: "icon", options?: IconOptions) => void

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

---

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

Signature

selectLineTool(linetool: "emoji", options?: EmojiOptions) => void

Parameters

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

Returns

​void

---

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

Signature

selectLineTool(linetool: SupportedLineTools, options?: EmojiOptions | IconOptions) => void

Parameters

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

Returns

​void

---

selectedLineTool

Get the currently selected drawing or cursor.

Signature

selectedLineTool() => SupportedLineTools

Returns

An identifier for drawing or cursor.

​SupportedLineTools

---

setActiveChart

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.

Signature

setActiveChart(index: number) => void

Parameters

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

Returns

​void

---

setDebugMode

Enable or disable debug mode.

Signature

setDebugMode(enabled: boolean) => void

Parameters

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

Returns

​void

---

setLayout

Set the current chart layout type.

Params

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

Signature

setLayout(layout: LayoutType) => void

Parameters

Name	Type
layout	LayoutType

Returns

​void

---

setSymbol

Set the symbol and resolution of the active chart.

Signature

setSymbol(symbol: string, interval: ResolutionString, callback: EmptyCallback) => void

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

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

Signature

showConfirmDialog(params: DialogParams<Function>) => void

Parameters

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

Returns

​void

---

showLoadChartDialog

Show the "Load Chart Layout" dialog.

Signature

showLoadChartDialog() => void

Returns

​void

---

showNoticeDialog

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

Signature

showNoticeDialog(params: DialogParams<Function>) => void

Parameters

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

Returns

​void

---

showSaveAsChartDialog

Show the "Copy Chart Layout" dialog.

Signature

showSaveAsChartDialog() => void

Returns

​void

---

startFullscreen

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

Signature

startFullscreen() => void

Returns

​void

---

subscribe

Subscribe to library events.

Signature

subscribe<EventName>(event: EventName, callback: SubscribeEventsMap[EventName]) => void

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

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.

Signature

supportedChartTypes() => IWatchedValueReadonly<ChartStyle[]>

Returns

​IWatchedValueReadonly<ChartStyle[]>

---

symbolInterval

Get the symbol and interval of the active chart.

Signature

symbolInterval() => SymbolIntervalResult

Returns

​SymbolIntervalResult

---

symbolSync

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

Signature

symbolSync() => IWatchedValue<boolean>

Returns

A watched value of the state of the symbol sync.

​IWatchedValue<boolean>

---

takeClientScreenshot

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

Signature

takeClientScreenshot(options?: Partial<ClientSnapshotOptions>) => Promise<HTMLCanvasElement>

Parameters

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

Returns

A promise containing a HTMLCanvasElement of the snapshot.

​Promise<HTMLCanvasElement>

---

takeScreenshot

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.

Signature

takeScreenshot() => void

Returns

​void

---

timeHoursFormat

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

Signature

timeHoursFormat() => IWatchedValue<TimeHoursFormat>

Returns

​IWatchedValue<TimeHoursFormat>

---

timeSync

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

Signature

timeSync() => IWatchedValue<boolean>

Returns

A watched value of the state of the time sync.

​IWatchedValue<boolean>

---

undoRedoState

Get the state of the undo/redo stack.

Signature

undoRedoState() => UndoRedoState

Returns

​UndoRedoState

---

unsubscribe

Unsubscribe from library events.

Signature

unsubscribe<EventName>(event: EventName, callback: SubscribeEventsMap[EventName]) => void

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

Trading Terminal 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']);

Signature

watchList() => Promise<IWatchListApi>

Returns

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

​Promise<IWatchListApi>

---

watermark

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)

Signature

watermark() => IWatermarkApi

Returns

An API object for adjusting the watermark settings.

​IWatermarkApi

---

widgetbar

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

Signature

widgetbar() => Promise<IWidgetbarApi>

Returns

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

​Promise<IWidgetbarApi>