Skip to main content
Version: v26

ChartingLibraryWidgetOptions

Interface

Properties

additional_symbol_info_fields

Optional

An optional field containing an array of custom symbol info fields to be shown in the Symbol Info dialog.

See Symbology for more information about symbol info.

additional_symbol_info_fields: [
{ title: 'Ticker', propertyName: 'ticker' }
]

Type

AdditionalSymbolInfoField[]


auto_save_delay

Optional

A threshold delay in seconds that is used to reduce the number of onAutoSaveNeeded calls.

auto_save_delay: 5,

Type

number


autosize

Optional

Boolean value showing whether the chart should use all the available space in the container and resize when the container itself is resized.

Default

false

autosize: true,

Type

boolean


charts_storage_api_version

Optional

A version of your backend. Supported values are: "1.0" | "1.1". Study Templates are supported starting from version "1.1".

charts_storage_api_version: "1.1",

Type

AvailableSaveloadVersions


charts_storage_url

Optional

Set the storage url endpoint for use with the high-level saving / loading charts API. See more details here.

charts_storage_url: 'http://storage.yourserver.com',

Type

string


client_id

Optional

Set the client ID for the high-level saving / loading charts API. See more details here.

client_id: 'yourserver.com',

Type

string


compare_symbols

Optional

an array of custom compare symbols for the Compare window.

Example:

compare_symbols: [
{ symbol: 'DAL', title: 'Delta Air Lines' },
{ symbol: 'VZ', title: 'Verizon' },
...
];

Type

CompareSymbol[]


container

The container can either be a reference to an attribute of a DOM element inside which the iframe with the chart will be placed or the HTMLElement itself.

container: "tv_chart_container",

or

container: document.getElementById("tv_chart_container"),

Type

string | HTMLElement


context_menu

Optional

You could use this object to override context menu. You can also change the menu on the fly using the IChartingLibraryWidget.onContextMenu method.

Type

ContextMenuOptions


customFormatters

DeprecatedOptional

Type

CustomFormatters


custom_css_url

Optional

Adds your custom CSS to the chart. url should be an absolute or relative path to the static folder.

custom_css_url: 'css/style.css',

Type

string


custom_font_family

Optional

Changes the font family used on the chart including the time scale, price scale, and chart's pane. If you want to customize fonts outside the chart, for example, within Watchlist or another widget, you should use the ChartingLibraryWidgetOptions.custom_css_url property to provide custom CSS styles.

Specify custom_font_family in Widget Constructor as follows:

custom_font_family: "'Inconsolata', monospace",

The custom_font_family value should have the same format as the font-family property in CSS. To use a font that is not available by default on your system, you should first add this font to your custom CSS. For example, the code sample below imports a Google font into your custom CSS:

@import url('https://fonts.googleapis.com/css2?family=Inconsolata:wght@500&display=swap');

Type

string


custom_formatters

Optional

Custom formatters for adjusting the display format of price, date, and time values.

Example:

custom_formatters: {
timeFormatter: {
format: (date) => {
const _format_str = '%h:%m';
return _format_str
.replace('%h', date.getUTCHours(), 2)
.replace('%m', date.getUTCMinutes(), 2)
.replace('%s', date.getUTCSeconds(), 2);
}
},
dateFormatter: {
format: (date) => {
return date.getUTCFullYear() + '/' + (date.getUTCMonth() + 1) + '/' + date.getUTCDate();
}
},
tickMarkFormatter: (date, tickMarkType) => {
switch (tickMarkType) {
case 'Year':
return 'Y' + date.getUTCFullYear();

case 'Month':
return 'M' + (date.getUTCMonth() + 1);

case 'DayOfMonth':
return 'D' + date.getUTCDate();

case 'Time':
return 'T' + date.getUTCHours() + ':' + date.getUTCMinutes();

case 'TimeWithSeconds':
return 'S' + date.getUTCHours() + ':' + date.getUTCMinutes() + ':' + date.getUTCSeconds();
}

throw new Error('unhandled tick mark type ' + tickMarkType);
},
priceFormatterFactory: (symbolInfo, minTick) => {
if (symbolInfo?.fractional || minTick !== 'default' && minTick.split(',')[2] === 'true') {
return {
format: (price, signPositive) => {
// return the appropriate format
},
};
}
return null; // this is to use default formatter;
},
studyFormatterFactory: (format, symbolInfo) => {
if (format.type === 'price') {
const numberFormat = new Intl.NumberFormat('en-US', { notation: 'scientific' });
return {
format: (value) => numberFormat.format(value)
};
}

if (format.type === 'volume') {
return {
format: (value) => (value / 1e9).toPrecision(format?.precision || 2) + 'B'
};
}

if (format.type === 'percent') {
return {
format: (value) => `${value.toPrecision(format?.precision || 4)} percent`
};
}

return null; // this is to use default formatter;
},
}

Remark: tickMarkFormatter must display the UTC date, and not the date corresponding to your local timezone.

Type

CustomFormatters


custom_indicators_getter

Optional

Function that returns a Promise object with an array of your custom indicators.

PineJS variable will be passed as the first argument of this function and can be used inside your indicators to access internal helper functions.

See more details here.

custom_indicators_getter: function(PineJS) {
return Promise.resolve([
// *** your indicator object, created from the template ***
]);
},

Type

(PineJS: PineJS) => Promise<readonly CustomIndicator[]>

Type declaration

Function that returns a Promise object with an array of your custom indicators.

PineJS variable will be passed as the first argument of this function and can be used inside your indicators to access internal helper functions.

See more details here.

custom_indicators_getter: function(PineJS) {
return Promise.resolve([
// *** your indicator object, created from the template ***
]);
},

Signature

(PineJS: PineJS) => Promise<readonly CustomIndicator[]>
Parameters
NameType
PineJSPineJS
Returns

Promise<readonly CustomIndicator[]>


custom_timezones

Optional

List of custom timezones.

Please see the timezones documentation for more details.

Type

CustomAliasedTimezone[]


custom_translate_function

Optional

Use this property to set your own translation function. key and options will be passed to the function.

You can use this function to provide custom translations for some strings.

The function should return either a string with a new translation or null to fallback to the default translation.

For example, if you want to rename "Trend Line" shape to "Line Shape", then you can do something like this:

custom_translate_function: (key, options, isTranslated) => {
if (key === 'Trend Line') {
// patch the title of trend line
return 'Line Shape';
}

return null;
}

Type

CustomTranslateFunction


datafeed

JavaScript object that implements the datafeed interface (IBasicDataFeed) to supply the chart with data. See Connecting Data for more information on the JS API.

datafeed: new Datafeeds.UDFCompatibleDatafeed("https://demo_feed.tradingview.com")

Type

IBasicDataFeed | IDatafeedChartApi & IExternalDatafeed & IDatafeedQuotesApi


debug

Optional

Setting this property to true will make the chart write detailed API logs into the browser console. Alternatively, you can use the charting_library_debug_mode featureset to enable it, or use the setDebugMode widget method (IChartingLibraryWidget.setDebugMode) .

debug: true,

Type

boolean


disabled_features

Optional

The array containing names of features that should be disabled by default. Feature means part of the functionality of the chart (part of the UI/UX). Supported features are listed here.

Example:

disabled_features: ["header_widget", "left_toolbar"],

Type

ChartingLibraryFeatureset[]


drawings_access

Optional

You can hide some drawings from the toolbar or add custom restrictions for applying them to the chart.

This property has the same structure as the studies_access argument. Use the same names as you see in the UI.

Remark: There is a special case for font-based drawings. Use the "Font Icons" name for them. Those drawings cannot be enabled or disabled separately - the entire group will have to be either enabled or disabled.

Example

drawings_access: {
type: 'black',
tools: [
{
name: 'Trend Line',
grayed: true
},
]
},

Type

AccessList


enabled_features

Optional

The array containing names of features that should be enabled by default. Feature means part of the functionality of the chart (part of the UI/UX). Supported features are listed here.

Example:

enabled_features: ["move_logo_to_main_pane"],

Type

ChartingLibraryFeatureset[]


favorites

Optional

Items that should be marked as favorite by default. This option requires that the usage of localstorage is disabled (see featuresets to know more). The favorites property is supposed to be an object. The following properties are supported:

favorites: {
intervals: ["1D", "3D", "3W", "W", "M"],
indicators: ["Awesome Oscillator", "Bollinger Bands"],
drawingTools: ['LineToolBrush', 'LineToolCallout', 'LineToolCircle'],
chartTypes: ['Area', 'Candles'],
},

If you want to allow users to add/remove items from favorites, you should enable/disable the items_favoriting featureset.

Type

Favorites<ChartTypeFavorites>


fullscreen

Optional

Boolean value showing whether the chart should use all the available space in the window.

Default

false

fullscreen: true,

Type

boolean


header_widget_buttons_mode

Optional

An additional optional field to change the look and feel of buttons on the top toolbar.

By default (if option is omitted) header will be in adaptive mode (fullsize if the window width allows and icons on smaller windows).

Example:

header_widget_buttons_mode: 'fullsize',

Type

HeaderWidgetButtonsMode


height

Optional

The desired height of a widget. Please make sure that there is enough space for the widget to be displayed correctly.

height: 600,

Remark: If you want the chart to use all the available space use the fullscreen parameter instead of setting it to '100%'.

Type

number


interval

The default interval for the chart.

Example:

interval: '1D',

Type

ResolutionString


library_path

Optional

A path to a static folder.

library_path: "charting_library/",

Type

string


load_last_chart

Optional

Set this parameter to true if you want the library to load the last saved chart for a user (you should implement save/load first to make it work).

load_last_chart: true,

Type

boolean


loading_screen

Optional

Customization of the loading spinner. Value is an object with the following possible keys:

  • backgroundColor
  • foregroundColor

Example:

loading_screen: { backgroundColor: "#000000" }

Type

LoadingScreenOptions


locale

Locale to be used by the library. See Localization section for details.

locale: 'en',

Type

LanguageCode


numeric_formatting

Optional

The object containing formatting options for numbers. The only possible option is decimal_sign currently.

numeric_formatting: { decimal_sign: "," },

Type

NumericFormattingParams


overrides

Optional

Override values for the default widget properties You can override most of the properties (which also may be edited by user through UI) using overrides parameter of Widget constructor. overrides is supposed to be an object. The keys of this object are the names of overridden properties. The values of these keys are the new values of the properties.

Example:

overrides: {
"mainSeriesProperties.style": 2
}

This code will change the default series style to "line". All customizable properties are listed in separate article.

Type

Partial<WidgetOverrides>


save_load_adapter

Optional

An object containing the save/load functions. It is used to implement a custom save/load algorithm. Please see details and an example on Saving and Loading Charts page.

Type

IExternalSaveLoadAdapter


saved_data

Optional

JS object containing saved chart content. Use this parameter when creating the widget if you have a saved chart already. If you want to load the chart content when the chart is initialized then use load() method (IChartingLibraryWidget.load) of the widget.

Type

object


saved_data_meta_info

Optional

JS object containing saved chart content meta info.

Type

SavedStateMetaInfo


settings_adapter

Optional

An object that contains set/remove functions. Use it to save chart settings to your preferred storage (including server-side).

Example:

settings_adapter: {
initialSettings: { ... },
setValue: function(key, value) { ... },
removeValue: function(key) { ... },
}

Type

ISettingsAdapter


settings_overrides

Optional

The object that contains new values for values saved to the settings. These overrides will replace any matching values from the settings, regardless of where the settings are loaded from (i.e. local storage or a custom settings adapter). The object is similar to the overrides object.

overrides will not affect values that have been saved to settings so this option can be used instead.

settings_overrides: {
"linetooltrendline.linecolor": "blue"
}

Type

Overrides


snapshot_url

Optional

This URL is used to send a POST request with binary chart snapshots when a user presses the snapshot button. This POST request contains multipart/form-data with the field preparedImage that represents binary data of the snapshot image in image/png format.

This endpoint should return the full URL of the saved image in the the response.

snapshot_url: "https://myserver.com/snapshot",

Type

string


studies_access

Optional

You can hide some studies from the toolbar or add custom restrictions for applying them to the chart.

Example

studies_access: {
type: "black" | "white",
tools: [
{
name: "<study name>",
grayed: true
},
< ... >
]
}

Type

AccessList


studies_overrides

Optional

Use this option to customize the style or inputs of the indicators. You can also customize the styles and inputs of the Compare series using this argument. Refer to Indicator Overrides for more information. Overrides for built-in indicators are listed in StudyOverrides.

studies_overrides: {
"volume.volume.color.0": "#00FFFF",
},

Type

StudyOverrides


study_count_limit

Optional

Maximum amount of studies allowed at one time within the layout. Minimum value is 2.

study_count_limit: 5,

Type

number


symbol

Optional

The default symbol for the chart.

Example:

symbol: 'AAPL',

Type

string


symbol_search_complete

Optional

Use this property to set a function to override the symbol input from the Symbol Search.

For example, you may want to get additional input from the user before deciding which symbol should be resolved.

The function should take two parameters: a string of input from the Symbol Search and a optional search result item. It should return a Promise that resolves with a symbol ticker and a human-friendly symbol name.

NOTE: This override is not called when adding a symbol to the watchlist.

{
// `SearchSymbolResultItem` is the same interface as for items returned to the Datafeed's searchSymbols result callback.
symbol_search_complete: (symbol: string, searchResultItem?: SearchSymbolResultItem) => {
return new Promise((resolve) => {
let symbol = getNewSymbol(symbol, searchResultItem);
let name = getHumanFriendlyName(symbol, searchResultItem)
resolve({ symbol: symbol, name: name });
});
}
}

Type

SymbolSearchCompleteOverrideFunction


symbol_search_request_delay

Optional

A threshold delay in milliseconds that is used to reduce the number of search requests when the user enters the symbol name in the Symbol Search.

symbol_search_request_delay: 1000,

Type

number


theme

Optional

Set predefined custom theme color for the chart. Supported values are: "light" | "dark".

theme: "light",

Type

ThemeName


time_frames

Optional

List of visible time frames that can be selected at the bottom of the chart. See Time frame toolbar for more information. Time frame is an object containing the following properties:

Example:

time_frames: [
{ text: "50y", resolution: "6M", description: "50 Years" },
{ text: "3y", resolution: "1W", description: "3 Years", title: "3yr" },
{ text: "8m", resolution: "1D", description: "8 Month" },
{ text: "3d", resolution: "5", description: "3 Days" },
{ text: "1000y", resolution: "1W", description: "All", title: "All" },
]

Type

TimeFrameItem[]


time_scale

Optional

An additional optional field to add more bars on screen.

Example:

time_scale: {
min_bar_spacing: 10,
}

Type

TimeScaleOptions


timeframe

Optional

Sets the default timeframe of the chart.

The timeframe can be relative to the current date, or a range.

A relative timeframe is a number with a letter D for days and M for months:

timeframe: '3M',

A range is an object with to and from properties. The to and from properties should be UNIX timestamps:

timeframe: { from: 1640995200, to: 1643673600 } // from 2022-01-01 to 2022-02-01

Note: When using a range the chart will still request data up to the current date. This is to enable scrolling forward in time once the chart has loaded.

Type

TimeframeOption


timezone

Optional

Default timezone of the chart. The time on the timescale is displayed according to this timezone. See the list of supported timezones for available values. Set it to exchange to use the exchange timezone. Use the ChartingLibraryWidgetOptions.overrides section if you wish to override the default value.

timezone: "America/New_York",

Type

"exchange" | Timezone


toolbar_bg

Optional

Background color of the toolbars.

toolbar_bg: '#f4f7f9',

Type

string


user_id

Optional

Set the user ID for the high-level saving / loading charts API. See more details here.

user_id: 'public_user_id',

Type

string


width

Optional

The desired width of a widget. Please make sure that there is enough space for the widget to be displayed correctly.

width: 300,

Remark: If you want the chart to use all the available space use the fullscreen parameter instead of setting it to '100%'.

Type

number