Skip to main content
Version: v25

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

NameTypeDescription
urlstringA 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

NameType
TOverridesextends Partial<ChartPropertiesOverrides>

Parameters

NameTypeDescription
overridesTOverridesAn 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

NameTypeDescription
overridesobjectAn 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

NameTypeDescription
themeNameThemeNameA theme name.
options?ChangeThemeOptionsAn 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

NameTypeDescription
index?numberZero 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

NameTypeDescription
options?CreateHTMLButtonOptionsA 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

NameTypeDescription
options?CreateTradingViewStyledButtonOptionsA 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

NameTypeDescription
options?CreateButtonOptionsA 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

NameType
paramsDropdownParams

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

NameTypeDescription
callback(chartRecords: SaveLoadChartRecord[]) => voidA 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

NameTypeDescription
studyNamestringThe name of a study.

Returns

StudyInputInformation[]


getStudyStyles

Get information about the styles of a study.

Signature

getStudyStyles(studyName: string) => StudyStyleInfo

Parameters

NameTypeDescription
studyNamestringThe 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

NameTypeDescription
stateobjectA chart state object to load.
extendedData?SavedStateMetaInfoA optional object of information about the saved state.

Returns

void


loadChartFromServer

Load a saved chart from the server.

Signature

loadChartFromServer(chartRecord: SaveLoadChartRecord) => void

Parameters

NameTypeDescription
chartRecordSaveLoadChartRecordA 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


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

NameTypeDescription
callbackEmptyCallbackA 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

NameTypeDescription
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

NameTypeDescription
callback(obj: GrayedObject) => voidA 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

NameTypeDescription
shortCutstring | number | (string | number)[]A number, a string, or an array of number and string.
callbackEmptyCallbackA 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

NameTypeDescription
chartIdstringA chart ID from a SaveLoadChartRecord (returned by getSavedCharts).
onCompleteCallbackEmptyCallbackA 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

NameTypeDescription
callback(state: object) => voidA 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

NameTypeDescription
onComplete?EmptyCallbackAn optional callback function called when the chart is successfully saved.
onFail?EmptyCallbackAn optional callback function called when the chart fails to save.
options?SaveChartToServerOptionsAn 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

NameTypeDescription
linetool"icon"An icon drawing tool.
options?IconOptionsAn 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

NameTypeDescription
linetoolOmit<"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

NameTypeDescription
linetool"icon"Icon line tool.
options?IconOptionsAn 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

NameTypeDescription
linetool"emoji"Emoji line tool.
options?EmojiOptionsOptions 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

NameTypeDescription
linetoolSupportedLineToolsA drawing or cursor to select.
options?EmojiOptions | IconOptionsAn 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

NameTypeDescription
indexnumberindex 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

NameTypeDescription
enabledbooleanA 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

NameType
layoutLayoutType

Returns

void


setSymbol

Set the symbol and resolution of the active chart.

Signature

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

Parameters

NameTypeDescription
symbolstringA symbol to load.
intervalResolutionStringA interval (resolution) to load.
callbackEmptyCallbackA 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

NameTypeDescription
paramsDialogParams<(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

NameTypeDescription
paramsDialogParams<() => 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

NameType
EventNameextends keyof SubscribeEventsMap

Parameters

NameTypeDescription
eventEventNameA event to subscribe to.
callbackSubscribeEventsMap[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

NameTypeDescription
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

NameType
EventNameextends keyof SubscribeEventsMap

Parameters

NameTypeDescription
eventEventNameA event to unsubscribe from.
callbackSubscribeEventsMap[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>