Skip to main content

Interface: IWatchListApi

Charting Library.IWatchListApi

An API object for interacting with the Watchlist widget. The Watchlist is a widget that allows users to track price movements and volume of specific financial instruments in real-time. Watchlists also allow users to quickly switch between the symbols. The Watchlist widget is displayed on the widget panel on the right side of the chart.

Notes about watchlist contents

Watchlist items should be symbol names which your datafeed resolveSymbol method can resolve. This means that generally shorter names such as AAPL can be used if your datafeed understands it. However, it is recommend that you provide the symbol names as they appear within the LibrarySymbolInfo object, for example, NASDAQ:AAPL.

Methods​

createList​

createList(listName?, symbols?, listId?): WatchListSymbolList

Create a list of symbols with listName name. If the listName parameter is not provided or there is no WatchList then null will be returned;

Parameters​

NameTypeDescription
listName?stringname for the watchlist
symbols?string[]Symbol IDs for the watchlist. Any list item that has the ### prefix is considered a section divider in the watchlist.
listId?stringCustom ID for the watchlist. When provided, if a watchlist with this ID already exists it will be updated with the given symbols instead of creating a duplicate. This allows syncing watchlist IDs with a remote backend to ensure consistency across tabs and prevent duplicate lists from being created. If omitted, a random ID is generated.

Returns​

WatchListSymbolList — WatchListSymbolList

defaultList​

defaultList(): string[]

Get a default list of symbols.

Returns​

string[] — default list of symbols

deleteList​

deleteList(listId): void

Delete a watchlist of symbols

Parameters​

NameTypeDescription
listIdstringwatchlist ID

getActiveListId​

getActiveListId(): string

Get the ID of the current watchlist. If there is no WatchList then null will be returned.

Returns​

string — id of active watchlist

getAllLists​

getAllLists(): WatchListSymbolListMap

Get all watchlists. If there is no WatchList then null will be returned.

Returns​

WatchListSymbolListMap — object of all watchlists

getList​

getList(id?): string[]

Get a list of symbols. If the id parameter is not provided, the current list will be returned. If there is no watchList, null will be returned.

Parameters​

NameTypeDescription
id?stringWatchlist ID

Returns​

string[] — list of symbols for watchlist

onActiveListChanged​

onActiveListChanged(): ISubscription<EmptyCallback>

Subscription for when the active watchlist is changed to a different list. Use the subscribe method of the returned ISubscription object to subscribe to the notifications.

Returns​

ISubscription<EmptyCallback>

onListAdded​

onListAdded(): ISubscription<WatchListSymbolListAddedCallback>

Subscription for when a new list is added to the watchlist widget. Use the subscribe method of the returned ISubscription object to subscribe to the notifications.

Returns​

ISubscription<WatchListSymbolListAddedCallback>

onListChanged​

onListChanged(): ISubscription<WatchListSymbolListChangedCallback>

Subscription for when the symbols of the active watchlist are changed. Use the subscribe method of the returned ISubscription object to subscribe to the notifications.

Returns​

ISubscription<WatchListSymbolListChangedCallback>

onListRemoved​

onListRemoved(): ISubscription<WatchListSymbolListRemovedCallback>

Subscription for when a list is removed from the watchlist widget. Use the subscribe method of the returned ISubscription object to subscribe to the notifications.

Returns​

ISubscription<WatchListSymbolListRemovedCallback>

onListRenamed​

onListRenamed(): ISubscription<WatchListSymbolListRenamedCallback>

Subscription for when a list is renamed. Use the subscribe method of the returned ISubscription object to subscribe to the notifications.

Returns​

ISubscription<WatchListSymbolListRenamedCallback>

renameList​

renameList(listId, newName): void

Rename the watchlist.

Parameters​

NameTypeDescription
listIdstringID of the watchlist
newNamestringNew name to set for the watchlist

saveList​

saveList(list): boolean

Save a list of symbols.

Parameters​

NameType
listWatchListSymbolList

Returns​

boolean — If there is no watchList or an equivalent list already exists, false will be returned. Otherwise, true will be returned.

setActiveList​

setActiveList(id): void

Make the watchlist with the specified id active.

Parameters​

NameTypeDescription
idstringwatchlist ID

setList​

setList(symbols): void

Obsolete. Use updateList instead.

Set the list of symbols for the watchlist. It will replace the entire list.

Parameters​

NameTypeDescription
symbolsstring[]symbol IDs

updateList​

updateList(listId, symbols): void

Edit the list of symbols for a watchlist.

Parameters​

NameTypeDescription
listIdstringID of the watchlist
symbolsstring[]Symbols to be set for the watchlist. Any list item that has the ### prefix is considered a section divider in the watchlist.