Skip to Content
API ReferenceChart Widget

📊 Chart Widget API

The Chart Widget API provides programmatic control over the chart through the ChartInstance component. This includes methods for changing symbols, intervals, themes, managing indicators/drawings, and controlling multichart layouts.

🚀 Quick Start

Accessing ChartInstance

The ChartInstance is available through two methods:

import { createChart } from "@gocharting/chart-sdk";
 
// Method 1: Use onReady callback (recommended)
const chart = createChart("#chart-container", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
	onReady: (chartInstance) => {
		// chartInstance has all control methods
		chartInstance.setSymbol("MSFT");
		chartInstance.setInterval("1H");
		chartInstance.setTheme("dark");
	},
});
 
// Method 2: Get from ChartWrapper
const chartInstance = chart.getChartInstance();
chartInstance.setSymbol("GOOGL");

Basic Usage Examples

// Change symbol
chartInstance.setSymbol("AAPL");
 
// Change interval
chartInstance.setInterval("1H");
 
// Change theme
chartInstance.setTheme("dark");
 
// Resize chart
chartInstance.resize(800, 600);
 
// For multichart layouts, change symbol on specific chart
chartInstance.setChartSymbolAtIndex("MSFT", 1);
 
// Change interval on specific chart
chartInstance.setIntervalAtIndex("15m", 1);

📋 ChartInstance Methods

All methods below are called on the ChartInstance object, which you can access via onReady callback or chart.getChartInstance().

Basic Control Methods

destroy()

Destroys the chart and cleans up all resources.

chartInstance.destroy();

Returns: void

setSymbol(newSymbol)

Changes the displayed symbol on the currently selected chart.

chartInstance.setSymbol("AAPL");
chartInstance.setSymbol("BYBIT:FUTURE:BTCUSDT");

Parameters:

  • newSymbol (string): Symbol identifier (e.g., “AAPL”, “BYBIT:FUTURE:BTCUSDT”)

Returns: void

setInterval(newInterval)

Changes the time interval on the currently selected chart.

chartInstance.setInterval("1H");
chartInstance.setInterval("5m");

Parameters:

  • newInterval (string): Time interval (‘1m’, ‘5m’, ‘15m’, ‘30m’, ‘1H’, ‘4H’, ‘1D’, ‘1W’, ‘1M’)

Returns: void

setTheme(newTheme)

Changes the chart theme dynamically without recreating the chart.

// Switch to dark theme
chartInstance.setTheme("dark");
 
// Switch to light theme
chartInstance.setTheme("light");
 
// Toggle theme based on user preference
const currentTheme = isDarkMode ? "dark" : "light";
chartInstance.setTheme(currentTheme);

Parameters:

  • newTheme (“light” | “dark”): Theme name

Returns: void

Live Demo:

resize(width, height)

Resizes the chart.

chartInstance.resize(800, 600);
chartInstance.resize("100%", "500px");

Parameters:

  • width (number | string): New width
  • height (number | string): New height

Returns: void

Multichart Methods

These methods are used for controlling specific charts in multichart layouts (e.g., 2x2, 3x3 grids).

setChartSymbolAtIndex(newSymbol, chartIdx)

Changes the displayed symbol on a specific chart by index.

chartInstance.setChartSymbolAtIndex("MSFT", 0);
chartInstance.setChartSymbolAtIndex("GOOGL", 1);

Parameters:

  • newSymbol (string): Symbol identifier
  • chartIdx (number): Chart index (0-based)

Returns: void

setIntervalAtIndex(newInterval, chartIdx)

Changes the time interval on a specific chart by index.

chartInstance.setIntervalAtIndex("1H", 0);
chartInstance.setIntervalAtIndex("15m", 1);

Parameters:

  • newInterval (string): Time interval
  • chartIdx (number): Chart index (0-based)

Returns: void

Indicator Methods

addIndicator(indicator)

Adds an indicator to the currently selected chart.

chartInstance.addIndicator({ type: "RSI", id: "rsi-1" });
chartInstance.addIndicator({ type: "MACD", id: "macd-1" });

Parameters:

  • indicator (object): Indicator object with type and id properties

Returns: void

addIndicatorAtIndex(indicator, chartIdx)

Adds an indicator to a specific chart by index in multichart mode.

chartInstance.addIndicatorAtIndex({ type: "RSI", id: "rsi-1" }, 0);
chartInstance.addIndicatorAtIndex({ type: "MACD", id: "macd-1" }, 1);

Parameters:

  • indicator (object): Indicator object with type and id properties
  • chartIdx (number): Chart index (0-based)

Returns: void

Drawing Methods

addDrawing(drawing, chartId?)

Adds a drawing to the currently selected chart.

chartInstance.addDrawing({
	type: "trendline",
	name: "My Trendline",
	options: { /* drawing options */ },
	appearance: { color: "#FF0000", lineWidth: 2 },
});

Parameters:

  • drawing (object): Drawing object with type/name, options, and appearance properties
  • chartId (string, optional): Chart ID (default: “MAIN_CHART”)

Returns: void

addDrawingAtIndex(drawing, chartIdx, chartId?)

Adds a drawing to a specific chart by index in multichart mode.

chartInstance.addDrawingAtIndex(
	{
		type: "trendline",
		name: "My Trendline",
		options: { /* drawing options */ },
		appearance: { color: "#FF0000", lineWidth: 2 },
	},
	0
);

Parameters:

  • drawing (object): Drawing object
  • chartIdx (number): Chart index (0-based)
  • chartId (string, optional): Chart ID (default: “MAIN_CHART”)

Returns: void

deleteObject(objectId, chartId?)

Deletes an object (drawing or indicator) from the currently selected chart.

chartInstance.deleteObject("rsi-1");
chartInstance.deleteObject("trendline-1", "MAIN_CHART");

Parameters:

  • objectId (string): ID of the object to delete
  • chartId (string, optional): Chart ID (default: “MAIN_CHART”)

Returns: void

deleteObjectAtIndex(objectId, chartIdx, chartId?)

Deletes an object from a specific chart by index in multichart mode.

chartInstance.deleteObjectAtIndex("rsi-1", 0);
chartInstance.deleteObjectAtIndex("trendline-1", 1, "MAIN_CHART");

Parameters:

  • objectId (string): ID of the object to delete
  • chartIdx (number): Chart index (0-based)
  • chartId (string, optional): Chart ID (default: “MAIN_CHART”)

Returns: void

Settings Methods

updateSettings(settings)

Updates chart settings for the currently selected chart.

chartInstance.updateSettings({
	zone: "America/New_York",
	showGrid: true,
	showVolume: true,
});

Parameters:

  • settings (Partial<ChartSettings>): Settings object to update

Returns: void

updateSettingsAtIndex(settings, chartIdx)

Updates chart settings for a specific chart by index in multichart mode.

chartInstance.updateSettingsAtIndex(
	{
		zone: "America/New_York",
		showGrid: true,
	},
	0
);

Parameters:

  • settings (Partial<ChartSettings>): Settings object to update
  • chartIdx (number): Chart index (0-based)

Returns: void

State Management Methods

getChartState()

Gets the complete chart state for the currently selected chart.

const state = chartInstance.getChartState();
console.log(state.config.settings);

Returns: ChartState | null - The complete chart state object, or null if chart is not available

getChartStateAtIndex(chartIdx)

Gets the complete chart state for a specific chart by index in multichart mode.

const state = chartInstance.getChartStateAtIndex(0);
console.log(state.config.settings);

Parameters:

  • chartIdx (number): Chart index (0-based)

Returns: ChartState | null

setChartState(newState)

Sets the complete chart state for the currently selected chart.

const state = chartInstance.getChartState();
state.config.settings.showGrid = true;
chartInstance.setChartState(state);

Parameters:

  • newState (ChartState): The new chart state object to set

Returns: void

setChartStateAtIndex(newState, chartIdx)

Sets the complete chart state for a specific chart by index in multichart mode.

const state = chartInstance.getChartStateAtIndex(0);
state.config.settings.showGrid = true;
chartInstance.setChartStateAtIndex(state, 0);

Parameters:

  • newState (ChartState): The new chart state object to set
  • chartIdx (number): Chart index (0-based)

Returns: void

Trading Methods

setBrokerAccounts(data)

Sets broker account data for trading features.

chartInstance.setBrokerAccounts({
	accountList: [
		{
			id: "123",
			name: "Trading Account",
			balance: 10000,
			currency: "USD",
		},
	],
	orderBook: [],
	tradeBook: [],
	positions: [],
});

Parameters:

  • data (BrokerAccountData): Broker account data including accounts, orders, trades, and positions

Returns: void

Resubscription Methods

resubscribeAll(idToken?)

Resubscribes to all active subscriptions after reconnection. This handles candles (OHLCV), realtime ticks, compare symbols, and LIPI indicators.

Use Cases:

  1. Browser Tab Reactivation: When a browser tab is inactive for a long time, Chrome and other browsers deprioritize it to save resources. This causes WebSocket throughput to slow down significantly. When the tab becomes active again, call this method to rehydrate the charts with fresh data.

  2. WebSocket Reconnection: After a WebSocket disconnection and reconnection, call this method to resume all data streams.

  3. Authentication Token Refresh: When your authentication token is refreshed, pass the new token to resubscribe with updated credentials.

// Basic resubscription
chartInstance.resubscribeAll();
 
// With new authentication token
chartInstance.resubscribeAll(newIdToken);
 
// Example: Resubscribe when tab becomes visible
document.addEventListener("visibilitychange", () => {
	if (!document.hidden) {
		chartInstance.resubscribeAll();
	}
});

Parameters:

  • idToken (string, optional): New authentication token for resubscription

Returns: void

💡 Usage Examples

Example 1: Basic Symbol and Interval Changes

import { createChart } from "@gocharting/chart-sdk";
 
const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	onReady: (chartInstance) => {
		// Change symbol
		chartInstance.setSymbol("MSFT");
 
		// Change interval
		chartInstance.setInterval("1H");
 
		// Change theme
		chartInstance.setTheme("dark");
	},
});

Example 2: Multichart Layout Management

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	onReady: (chartInstance) => {
		// Set different symbols on different charts
		chartInstance.setChartSymbolAtIndex("AAPL", 0);
		chartInstance.setChartSymbolAtIndex("MSFT", 1);
		chartInstance.setChartSymbolAtIndex("GOOGL", 2);
		chartInstance.setChartSymbolAtIndex("AMZN", 3);
 
		// Set different intervals
		chartInstance.setIntervalAtIndex("1D", 0);
		chartInstance.setIntervalAtIndex("1H", 1);
		chartInstance.setIntervalAtIndex("15m", 2);
		chartInstance.setIntervalAtIndex("5m", 3);
	},
});

Example 3: Adding Indicators and Drawings

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	onReady: (chartInstance) => {
		// Add indicators
		chartInstance.addIndicator({ type: "RSI", id: "rsi-1" });
		chartInstance.addIndicator({ type: "MACD", id: "macd-1" });
 
		// Add drawing
		chartInstance.addDrawing({
			type: "trendline",
			name: "Support Line",
			options: {},
			appearance: { color: "#00FF00", lineWidth: 2 },
		});
 
		// Delete an indicator
		chartInstance.deleteObject("rsi-1");
	},
});

Example 4: Settings and State Management

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	onReady: (chartInstance) => {
		// Update settings
		chartInstance.updateSettings({
			zone: "America/New_York",
			showGrid: true,
			showVolume: true,
		});
 
		// Save chart state
		const state = chartInstance.getChartState();
		localStorage.setItem("chartState", JSON.stringify(state));
 
		// Restore chart state later
		const savedState = JSON.parse(localStorage.getItem("chartState"));
		if (savedState) {
			chartInstance.setChartState(savedState);
		}
	},
});

Example 5: Trading Integration

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	trading: {
		enableTrading: true,
	},
	onReady: (chartInstance) => {
		// Set broker accounts
		chartInstance.setBrokerAccounts({
			accountList: [
				{
					id: "123",
					name: "Trading Account",
					balance: 10000,
					currency: "USD",
				},
			],
			orderBook: [],
			tradeBook: [],
			positions: [],
		});
	},
});

Example 6: Resubscription After Tab Reactivation

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_KEY",
	onReady: (chartInstance) => {
		// Resubscribe when tab becomes visible
		document.addEventListener("visibilitychange", () => {
			if (!document.hidden) {
				console.log("Tab is now visible - resubscribing to data feeds");
				chartInstance.resubscribeAll();
			}
		});
	},
});

🔍 Method Reference Summary

CategoryMethodDescription
Basic Controldestroy()Destroy chart and clean up resources
setSymbol(newSymbol)Change symbol on current chart
setInterval(newInterval)Change interval on current chart
setTheme(newTheme)Change chart theme
resize(width, height)Resize the chart
MultichartsetChartSymbolAtIndex(newSymbol, chartIdx)Change symbol on specific chart
setIntervalAtIndex(newInterval, chartIdx)Change interval on specific chart
IndicatorsaddIndicator(indicator)Add indicator to current chart
addIndicatorAtIndex(indicator, chartIdx)Add indicator to specific chart
DrawingsaddDrawing(drawing, chartId?)Add drawing to current chart
addDrawingAtIndex(drawing, chartIdx, chartId?)Add drawing to specific chart
deleteObject(objectId, chartId?)Delete object from current chart
deleteObjectAtIndex(objectId, chartIdx, chartId?)Delete object from specific chart
SettingsupdateSettings(settings)Update settings for current chart
updateSettingsAtIndex(settings, chartIdx)Update settings for specific chart
StategetChartState()Get state of current chart
getChartStateAtIndex(chartIdx)Get state of specific chart
setChartState(newState)Set state of current chart
setChartStateAtIndex(newState, chartIdx)Set state of specific chart
TradingsetBrokerAccounts(data)Set broker account data
ResubscriptionresubscribeAll(idToken?)Resubscribe to all data feeds after reconnection

🔗 Related Documentation

For complete working examples, see the Examples section.

Last updated on
Chart APIConfiguration