API

This page documents the public API surface for ChartSpire, including constructor options, runtime methods, and integration callbacks.

Stylesheet (required)

ChartSpire is published as a JS module plus a separate global stylesheet. Import the CSS once before creating a chart:

import { ChartSpire } from 'chartspire'
import 'chartspire/style.css'

Asset	Bundler	CDN (unpkg)
JavaScript	chartspire → dist/chartspire-ui.js (ESM)	chartspire/bundle.js → dist/chartspire-ui.umd.js (global chartspireui)
Stylesheet	chartspire/style.css → dist/chartspire-ui.css	chartspire/style.css

CDN:

<script src="https://unpkg.com/chartspire/bundle.js"></script>
<link rel="stylesheet" href="https://unpkg.com/chartspire/style.css">

See Getting Started — Stylesheet (required) for install, peer dependency, and framework notes.

Creating chart

Create a chart instance by passing a configuration object to new ChartSpire(...).

For most implementations, start with container, symbol, interval, dataFeed, and enabledSymbolTypes, then add optional features as needed.

new ChartSpire(
  options: {
    bottomBarEnabled?: boolean;
    bottomBarIntervalEnabled?: boolean;
    candleCloseTimerEnabled?: boolean;
    candleTypeEnabled?: boolean;
    chartExportEnabled?: boolean;
    chartNavigationEnabled?: boolean;
    container: string | HTMLElement;
    dataFeed: DataFeed | string;
    dataFeedInitialHistoricalBars?: number;
    defaultOpenComponents?: ('watchlist' | 'orderbook' | 'trades' | 'objecttree')[];
    enabledSymbolTypes: SYMBOL_TYPE[];
    fontFamily?: string;
    fontWeight?: 'lighter' | 'normal' | 'bold' | 'bolder' | number
    fullscreenEnabled?: boolean;
    indicators?: string[]
    indicatorsEnabled?: boolean;
    interval: Interval;
    layoutLimit?: number;
    layoutsEnabled?: boolean;
    layoutUseExternalStorage?: boolean;
    leftBarEnabled?: boolean;
    locale?: string;
    logoEnabled?: boolean;
    menuPageClickCallback?: (page: MenuPage) => void;
    menuPages?: MenuPage[];
    menuPagesEnabled?: boolean;
    multiChartDelay?: number;
    multiChartEnabled?: boolean;
    multiChartLimit?: number;
    objectTreeEnabled?: boolean;
    orderBookDepthVisualization?: 'amount' | 'cumulative';
    orderBookEnabled?: boolean;
    orderBookMaxRows?: number;
    periods?: Interval[];
    replayEnabled?: boolean;
    rightBarEnabled?: boolean;
    screenshotEnabled?: boolean;
    settingsEnabled?: boolean;
    styles?: DeepPartial<Styles>;
    subscribedSymbolsURL?: string;
    symbol: SymbolInfo;
    symbolEnabled?: boolean;
    symbolSearchOnKeyStroke?: boolean;
    theme?: string;
    themeCustom?: CustomTheme[];
    themesEnabled?: boolean;
    timezone?: string;
    timezoneEnabled?: boolean;
    topBarEnabled?: boolean;
    topBarIntervalEnabled?: boolean;
    tradesEnabled?: boolean;
    tradesMaxRows?: number;
    tradesTimeFormat?: '12h' | '24h';
    watchListAmount?: number;
    watchListEnabled?: boolean;
    watchListHttp?: boolean;
    watchListHttpBatchSize?: number;
    watchListHttpInterval?: number;
    watchListHttpMaxRetries?: number;
    watchListHttpRetryEnabled?: boolean;
    watchListSubscriptionDelayMs?: number;
    watchListLimit?: number;
    watchListUseExternalStorage?: boolean;
    watermark?: string | Node;
  }
) => ChartSpire

• bottomBarEnabled Enable/disable the entire bottom bar (default: true).
• bottomBarIntervalEnabled Enable/disable interval selector in the bottom bar (default: true). Replaces the former intervalEnabled option. Has no effect when bottomBarEnabled is false.
• candleCloseTimerEnabled Whether to enable candle close timer on the price line
• candleTypeEnabled Enable/disable candle type selector in the top bar (default: true)
• chartExportEnabled Enable/disable chart data CSV export button in the top bar (default: true)
• chartNavigationEnabled Enable/disable chart navigation controls (zoom, move, reset) (default: true)
• container Container id or HTML element
• dataFeed Data feed implementation or a registered data feed name
• dataFeedInitialHistoricalBars Number of historical bars to request on the initial chart load before scroll pagination starts (default: 500)
• defaultOpenComponents Array of component names to open by default on page load. Maximum of 3 components. Valid values: 'watchlist', 'orderbook', 'trades', 'objecttree'. Components must be enabled to open (e.g., watchListEnabled: true)
• enabledSymbolTypes Array of SYMBOL_TYPE values to filter which symbol types are available in the UI. When specified, only these symbol types will appear in symbol search, watchlists, and other symbol-related features. If empty or omitted, all symbol types are available. Example: [SYMBOL_TYPE.STOCKS, SYMBOL_TYPE.CRYPTO]
• fontFamily Font family for the entire chart (e.g., 'Roboto', 'Arial, sans-serif', '"Inter", system-ui, sans-serif')
• fontWeight Font weight for the entire chart (e.g., 'normal', 'bold', '400', '600')
• fullscreenEnabled Enable/disable fullscreen button in the top bar (default: true)
• indicators Default indicators to display on the chart (e.g., ['SAR', 'VOL'])
• indicatorsEnabled Enable/disable the indicators button in the top bar (default: true)
• interval Time interval
• layoutLimit Maximum number of saved layouts
• layoutsEnabled Enable/disable layout selector in bottom bar (default: true)
• layoutUseExternalStorage Whether to use external storage for layouts
• leftBarEnabled Enable/disable the entire left bar (default: true).
• locale Language
• logoEnabled Enable/disable ChartSpire logo
• menuPages Array of menu pages to display in the topbar dropdown menu
• menuPagesEnabled Enable/disable the menu dropdown in the topbar (default: false)
• menuPageClickCallback Callback function called when user clicks on a menu page - receives the selected page object
• multiChartDelay Delay in milliseconds between mounting/unmounting charts during multichart switch
• multiChartEnabled Enable/disable multi-chart layout button in the top bar (default: true)
• multiChartLimit Maximum number of charts allowed (1, 2, 3, 4, 6, 8, 10, 12, 14, 16). Defaults to 16
• objectTreeEnabled Whether to enable the Object Tree component that displays chart properties, indicators, and overlays (default: true)
• orderBookDepthVisualization Order book depth visualization mode: 'amount' shows individual order quantities, 'cumulative' shows cumulative market depth (default: 'cumulative')
• orderBookEnabled Whether to enable order book functionality
• orderBookMaxRows Maximum number of rows to display in the order book (default: 10)
• periods All available time intervals
• replayEnabled Enable/disable replay button in the top bar (default: true)
• rightBarEnabled Enable/disable the entire right bar (default: true). When false, the right bar is hidden and chart content expands to fill the reclaimed horizontal space. Watchlist, order book, trades, and object tree UI in the right bar are unavailable unless you provide your own UI.
• screenshotEnabled Enable/disable screenshot button in the top bar (default: true)
• settingsEnabled Enable/disable settings button in the top bar (default: true)
• styles Core chart styles
• subscribedSymbolsURL URL for subscribed symbols
• symbol Symbol information object
• symbolEnabled Enable/disable symbol display and symbol search trigger in the top bar (default: true)
• symbolSearchOnKeyStroke Enable real-time symbol search that triggers on every keystroke (default: false). When enabled, search results update as you type. When disabled, search only triggers when Enter key is pressed
• theme Theme
• themesEnabled Enable/disable theme selector in bottom bar (default: true)
• themeCustom Custom chart theme, for more details refer to theme.md doc
• timezone Timezone
• timezoneEnabled Enable/disable timezone selector in bottom bar (default: true)
• topBarEnabled Enable/disable the entire top bar (default: true).
• topBarIntervalEnabled Enable/disable interval dropdown in the top bar (default: true)
• tradesEnabled Whether to enable trades (time and sales) functionality
• tradesMaxRows Maximum number of trade rows to display in the trades component (default: 50)
• tradesTimeFormat Time format for trade timestamps: '12h' for 12-hour format with AM/PM, '24h' for 24-hour format (default: '24h')
• watchListAmount Number of watchlist items to display
• watchListEnabled Whether to enable watchlist functionality
• watchListHttp Enable HTTP polling for watchlist prices instead of WebSocket streaming (default: false)
• watchListHttpBatchSize Maximum number of symbols to batch in a single HTTP request cycle (default: 10)
• watchListHttpInterval Interval in milliseconds between HTTP price requests for watchlist (default: 5000, minimum: 1000)
• watchListHttpMaxRetries Maximum number of retry attempts for failed HTTP requests (default: 3)
• watchListHttpRetryEnabled Enable retry logic for failed HTTP price requests (default: true)
• watchListSubscriptionDelayMs Delay in milliseconds between each symbol when the watchlist bulk-subscribes to the data feed (default: 0).
• watchListLimit Maximum number of items in the watchlist
• watchListUseExternalStorage Whether to use external storage for watchlist
• watermark Watermark

SymbolInfo Interface

Defines the symbol payload shape used when creating charts, switching symbols, and integrating data feeds.

interface SymbolInfo {
  symbol: string;
  type: SYMBOL_TYPE | 'UNKNOWN';
  name?: string;
  shortName?: string;
  exchange?: string;
  market?: string;
  pricePrecision?: number;
  volumePrecision?: number;
  priceCurrency?: string;
  logo?: string;
}

ChartID Interface

Represents a chart instance identifier in multi-chart mode for APIs that target a specific chart.

interface ChartID {
  id: string;
}

Chart API

These runtime methods let you control chart state after initialization (theme, symbol, interval, active chart, and lifecycle).

setTheme(theme)

(theme: string) => void

Set theme for all charts.

getTheme()

() => string

Get current theme.

setStyles(styles)

(styles: DeepPartial<Styles>) => void

Set core chart styles for all charts.

getStyles()

() => Styles

Get core chart styles from active chart.

setLocale(locale)

(locale: string) => void

Set language for all charts.

getLocale()

() => string

Get language from active chart.

setFontFamily(fontFamily)

(fontFamily: string) => void

Set font family for the entire widget. Accepts any valid CSS font-family value.

Examples:

// Set Roboto font with fallbacks
chart.setFontFamily('Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif')

// Set custom font with fallbacks
chart.setFontFamily('"Inter", "Helvetica Neue", Arial, sans-serif')

// Set system font
chart.setFontFamily('system-ui, sans-serif')

getFontFamily()

() => string

Get current font family setting.

setFontWeight(fontWeight)

(fontWeight: 'lighter' | 'normal' | 'bold' | 'bolder' | number) => void

Set font weight for the entire widget. Accepts any valid CSS font-weight value.

Examples:

// Set font weight using keywords
chart.setFontWeight('normal')
chart.setFontWeight('bold')
chart.setFontWeight('lighter')

// Set font weight using numeric values
chart.setFontWeight(400)  // normal
chart.setFontWeight(600)  // semi-bold
chart.setFontWeight(700)  // bold

getFontWeight()

() => string

Get current font weight setting.

setTimezone(timezone)

(timezone: string) => void

Set timezone for all charts.

getTimezone()

() => string

Get timezone from active chart.

setSymbol(symbol, chartId, dataFeed)

(symbol: SymbolInfo, chartId: ChartID, dataFeed: DataFeed) => void

Set symbol for a specific chart.

getSymbol(chartId)

(chartId: ChartID) => SymbolInfo | null

Get symbol for a specific chart.

setInterval(interval, chartId)

(interval: Interval, chartId: ChartID) => void

Set interval for a specific chart.

getInterval(chartId)

(chartId: ChartID) => Interval | null

Get interval for a specific chart.

getActiveChart()

() => Nullable<ChartInterface>

Get active chart.

getChart(chartId)

(chartId: ChartID) => Nullable<ChartInterface>

Get chart for a specific chart ID.

isActiveChart(chartId)

(chartId: ChartID) => boolean

Check if a specific chart is active.

Default Open Components

The defaultOpenComponents property allows you to specify which right-side panel components should be open by default when the chart loads. This is useful for creating a customized initial view for your users.

Basic Usage

Use this pattern when you want one or more right-side panels open as soon as the widget mounts.

const chart = new ChartSpire({
  // ... other options
  
  // Enable the components you want to use
  watchListEnabled: true,
  orderBookEnabled: true,
  tradesEnabled: true,
  
  // Open watchlist and orderbook by default
  defaultOpenComponents: ['watchlist', 'orderbook'],
})

Available Components

These are the component keys accepted by defaultOpenComponents.

• 'watchlist' - Symbol watchlist panel
• 'orderbook' - Order book panel
• 'trades' - Recent trades panel
• 'objecttree' - Object tree panel

Rules and Limitations

• Maximum of 3 components can be open at once
• Only enabled components will open (e.g., requires watchListEnabled: true for watchlist)
• Components are opened in the order specified in the array
• If more than 3 components are specified, only the first 3 will be used

Examples

The examples below show common default-open combinations and a complete configuration.

// Open just the watchlist
defaultOpenComponents: ['watchlist']

// Open watchlist and orderbook  
defaultOpenComponents: ['watchlist', 'orderbook']

// Open all three panels (max limit)
defaultOpenComponents: ['watchlist', 'orderbook', 'trades']

// This will only open the first 3 (excess ignored)
defaultOpenComponents: ['watchlist', 'orderbook', 'trades', 'objecttree']

// Complete configuration example
const chart = new ChartSpire({
  container: '#chart',
  symbol: { symbol: 'BTCUSDT', type: 'crypto' },
  dataFeed: new DefaultDataFeed({
    http: {
      baseUrl: 'https://api.example.com',
      endpoints: {
        search: '/v1/market-data/symbols',
        historical: '/v1/market-data/candles',
        price: '/v1/market-data/price'
      }
    },
    websocket: {
      enabled: true,
      url: 'wss://stream.example.com/v1/market-data'
    }
  }),
  
  // Enable components
  watchListEnabled: true,
  orderBookEnabled: true,
  tradesEnabled: true,
  
  // Open watchlist and orderbook by default
  defaultOpenComponents: ['watchlist', 'orderbook'],
  
  // ... other options
})

Theme API

Custom themes are registered via the themeCustom constructor option. See Theme Customization for the CustomTheme interface and examples.

setActiveChart(chartId)

(chartId: ChartID) => void

Set the active chart.

getMultiChart()

() => number

Get the current number of displayed charts.

getAllChartIds()

() => string[]

Get an array of all chart IDs that are available based on the multiChartLimit.

getVisibleChartIds()

() => string[]

Get an array of chart IDs that are currently visible based on the multiChart setting.

syncAllSymbolsToActiveChart()

() => void

Sync all charts to use the symbol from the active chart. When called, all visible charts will switch to display the same symbol as the currently active chart, while preserving their individual interval settings.

syncAllIntervalsToActiveChart()

() => void

Sync all charts to use the interval from the active chart. When called, all visible charts will switch to use the same time interval as the currently active chart, while preserving their individual symbols.

destroy()

() => void

Clean up resources and remove all charts.