ChartSpire

Appearance

Widget API ​

Constructor options and methods on a ChartSpire instance (ChartSpireInterface). These apply to the whole widget — initial configuration, shared UI state, every mounted chart, or widget lifecycle.

Type the constructor with ChartOptions from @chartspire/ui.

typescript
import { ChartSpire } from '@chartspire/ui'
import type { ChartOptions } from '@chartspire/ui'

const options: ChartOptions = { /* ... */ }
const chartspire = new ChartSpire(options)

chartspire.setTheme('Dark Theme')
chartspire.setLocale('en-US')
chartspire.setTimezone('America/New_York')

Not on this API (by design): multichart grid apply, sync toggles, layout CRUD, and watchlist CRUD. Those are UI flows and/or process-global host callbacks — see Multichart, Synchronization, Layouts, and Watchlists.

Multi-instance notes: locale, theme selection, fonts, and timezone are per widget. Process-global (shared across embeds in the same page): DataFeed registry, host storage/watchlist callbacks, custom theme CSS keyed by theme name, and origin-scoped localStorage keys (last writer wins).

Constructor ​

typescript
new ChartSpire(options: ChartOptions) => ChartSpire

Throws

  • If locale is set to a value that is not registered — register it with registerLocale first (default en-US is always registered).
  • If container is a string id and no element with that id exists (Container is null).
  • If dataFeed is a string name that is not registered with getDataFeedRegistry().

Constructor interval uses Interval (multiplier / timespan / text). Runtime chart period changes use engine Period (span / type) via the Chart API — ChartSpire converts between the two.

Required ​

typescript
{
  container: string | HTMLElement;
  dataFeed: DataFeed | string;
  enabledSymbolTypes: (SYMBOL_TYPE | string)[];
  interval: Interval;
  symbol: Symbol;
}
  • container — Container id or HTML element.
  • dataFeed — A DataFeed instance, or a name previously registered with getDataFeedRegistry().registerDataFeed(...).
  • enabledSymbolTypes — Symbol types available in search/UI filters. Required. Pass an empty array to allow all built-in types. See SymbolType.
  • interval — Initial timeframe. See Interval.
  • symbol — Initial symbol. See Symbol.

Appearance ​

typescript
{
  customStyles?: CustomStyleOverrides;
  debugLoggingEnabled?: boolean;
  fontFamily?: string;
  fontWeight?: 'lighter' | 'normal' | 'bold' | 'bolder' | number;
  logoEnabled?: boolean;
  theme?: string;
  themeCustom?: CustomTheme[];
  themesEnabled?: boolean;
  watermark?: string | Node;
}
  • customStyles — Widget-wide chart style overrides at init (candles, grid, axes, etc.). Prefer this over runtime per-chart styling when changes should apply to all charts and survive theme switches. See Custom Styles and CustomStyleOverrides.
  • debugLoggingEnabled — Enable verbose ChartSpire debug logs (default: false). Warnings and errors still log when disabled.
  • fontFamily — Font family for the widget UI and charts.
  • fontWeight — Font weight for the widget UI and charts.
  • logoEnabled — Show the ChartSpire logo (default: true).
  • theme — Initial theme. Built-ins use English keys (for example 'Dark Theme'). Custom themes accept name or displayName; the stored id is always CustomTheme.name. See Theme.
  • themeCustom — Custom themes to register at init. See CustomTheme.
  • themesEnabled — Show the theme selector in the bottom bar (default: true).
  • watermark — Optional watermark content.

Bars and chrome ​

typescript
{
  bottomBarEnabled?: boolean;
  bottomBarIntervalEnabled?: boolean;
  candleCloseTimerEnabled?: boolean;
  candleTypeEnabled?: boolean;
  chartExportEnabled?: boolean;
  chartNavigationEnabled?: boolean;
  fullscreenEnabled?: boolean;
  indicators?: string[];
  indicatorsEnabled?: boolean;
  leftBarEnabled?: boolean;
  locale?: string;
  menuPageClickCallback?: (page: MenuPage) => void;
  menuPages?: MenuPage[];
  menuPagesEnabled?: boolean;
  periods?: Interval[];
  replayEnabled?: boolean;
  rightBarEnabled?: boolean;
  screenshotEnabled?: boolean;
  settingsEnabled?: boolean;
  symbolEnabled?: boolean;
  symbolSearchOnKeyStroke?: boolean;
  timezone?: string;
  timezoneEnabled?: boolean;
  topBarEnabled?: boolean;
  topBarIntervalEnabled?: boolean;
}
  • bottomBarEnabled — Entire bottom bar (default: true).
  • bottomBarIntervalEnabled — Interval selector in the bottom bar (default: true). No effect when bottomBarEnabled is false.
  • candleCloseTimerEnabled — Candle close timer on the price line (default: false).
  • candleTypeEnabled — Candle type selector in the top bar (default: true).
  • chartExportEnabled — Chart data CSV export button in the top bar (default: true).
  • chartNavigationEnabled — Chart navigation controls (zoom, move, reset) (default: true).
  • fullscreenEnabled — Fullscreen button in the top bar (default: true).
  • indicators — Default indicators to display (for example ['SAR', 'VOL']).
  • indicatorsEnabled — Indicators button in the top bar (default: true).
  • leftBarEnabled — Entire left bar (default: true).
  • locale — Widget language (default: 'en-US'). Must be registered.
  • menuPages — Menu pages in the top bar dropdown. See MenuPage.
  • menuPagesEnabled — Menu dropdown in the top bar (default: false).
  • menuPageClickCallback — Called when the user selects a menu page.
  • periods — Available intervals in the interval pickers. Defaults to a built-in set (1m … 1Y).
  • replayEnabled — Replay button in the top bar (default: true).
  • rightBarEnabled — Entire right bar (default: true).
  • screenshotEnabled — Screenshot button in the top bar (default: true).
  • settingsEnabled — Settings button in the top bar (default: true).
  • symbolEnabled — Symbol display and search in the top bar (default: true).
  • symbolSearchOnKeyStroke — Search on every keystroke when true; otherwise on Enter (default: false).
  • timezone — Initial timezone (default: 'Etc/UTC').
  • timezoneEnabled — Timezone selector in the bottom bar (default: true).
  • topBarEnabled — Entire top bar (default: true).
  • topBarIntervalEnabled — Interval dropdown in the top bar (default: true).

Data loading ​

typescript
{
  dataFeedInitialHistoricalBars?: number;
}
  • dataFeedInitialHistoricalBars — Historical bars requested on the initial chart load before scroll pagination (default: 500).

Layouts ​

typescript
{
  layoutLimit?: number;
  layoutsEnabled?: boolean;
  layoutUseExternalStorage?: boolean;
}
  • layoutLimit — Maximum number of saved custom layouts (default: 20).
  • layoutsEnabled — Layout selector in the bottom bar (default: true).
  • layoutUseExternalStorage — Use host callbacks instead of localStorage. Register setGetStoreCallback / setUpdateStoreCallback / setDeleteStoreCallback before creating the widget.

Multichart ​

typescript
{
  multiChartDelay?: number;
  multiChartEnabled?: boolean;
  multiChartLimit?: number;
}
  • multiChartDelay — Delay in ms between mounting/unmounting charts on grid change (default: 500).
  • multiChartEnabled — Multichart layout button in the top bar (default: true).
  • multiChartLimit — Maximum charts allowed (1–16, default: 16). Invalid values fall back to 16.

Grid preset changes are UI-only — there is no setMultiChart method. Sync toggles live in the multichart modal only. See Multichart and Synchronization.

Right-side panels ​

typescript
{
  defaultOpenComponents?: ('watchlist' | 'orderbook' | 'trades' | 'objecttree')[];
  objectTreeEnabled?: boolean;
  orderBookDepthVisualization?: 'amount' | 'cumulative';
  orderBookEnabled?: boolean;
  orderBookMaxRows?: number;
  tradesEnabled?: boolean;
  tradesMaxRows?: number;
  tradesTimeFormat?: '12h' | '24h';
}
  • defaultOpenComponents — Right-side panels to open on load (max 3, enabled panels only). Example: ['watchlist', 'orderbook'].
  • objectTreeEnabled — Object Tree panel (default: true).
  • orderBookDepthVisualization — 'amount' or 'cumulative' (default: 'cumulative').
  • orderBookEnabled — Order book panel (default: false). Requires feed order-book methods.
  • orderBookMaxRows — Maximum order book rows (default: 10).
  • tradesEnabled — Trades (time and sales) panel (default: false). Requires feed trade methods.
  • tradesMaxRows — Maximum trade rows (default: 50).
  • tradesTimeFormat — '12h' or '24h' (default: '24h').

Watchlist ​

typescript
{
  watchListAmount?: number;
  watchListEnabled?: boolean;
  watchListHttp?: boolean;
  watchListHttpBatchSize?: number;
  watchListHttpInterval?: number;
  watchListHttpMaxRetries?: number;
  watchListHttpRetryEnabled?: boolean;
  watchListSubscriptionDelayMs?: number;
  watchListLimit?: number;
  watchListUseExternalStorage?: boolean;
}
  • watchListAmount — Number of watchlist tabs/lists (default: 5).
  • watchListEnabled — Watchlist panel (default: false).
  • watchListHttp — HTTP polling for watchlist prices instead of WebSocket (default: false).
  • watchListHttpBatchSize — Max symbols per HTTP request cycle (default: 10).
  • watchListHttpInterval — Milliseconds between HTTP price requests (default: 5000, minimum: 1000).
  • watchListHttpMaxRetries — Max retries for failed HTTP requests (default: 3).
  • watchListHttpRetryEnabled — Retry failed HTTP price requests (default: true).
  • watchListSubscriptionDelayMs — Delay between symbol subscriptions when bulk-subscribing (default: 0).
  • watchListLimit — Maximum items per watchlist (default: 50).
  • watchListUseExternalStorage — Use host callbacks instead of localStorage. Register setWatchListChangeCallback / setGetWatchListsCallback before creating the widget.

Appearance ​

setTheme(theme) ​

typescript
(theme: string) => void

Set the theme for all charts and UI in this widget.

Parameters

  • theme — Built-in English key or localized built-in label, or a custom theme name / displayName registered via themeCustom.

Returns — void

Custom themes are stored as CustomTheme.name (the data-theme attribute value). Invalid names are ignored (error logged).

typescript
chartspire.setTheme('Dark Theme')
chartspire.setTheme('corporate-blue') // CustomTheme.name or displayName

getTheme() ​

typescript
() => string

Returns — Current theme id (built-in English key, or custom theme name).

setCustomStyles(customStyles) ​

typescript
(customStyles: CustomStyleOverrides) => void

Set widget-wide persistent chart styles. Replaces the previous overrides. Survives theme switches. See Custom Styles.

Parameters

Returns — void

typescript
chartspire.setCustomStyles({
  global: {
    candle: { bar: { upColor: '#26a69a', downColor: '#ef5350' } },
  },
})

getCustomStyles() ​

typescript
() => CustomStyleOverrides | null

Returns — Current widget-wide overrides, or null if none are set.

clearCustomStyles() ​

typescript
() => void

Clear all widget-wide custom style overrides.

Returns — void

hasCustomStyles() ​

typescript
() => boolean

Returns — true if widget-wide custom style overrides are applied.

setFontFamily(fontFamily) ​

typescript
(fontFamily: string) => void

Set the font family for the widget.

Returns — void

typescript
chartspire.setFontFamily('Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif')
chartspire.setFontFamily('system-ui, sans-serif')

getFontFamily() ​

typescript
() => string

Returns — Current font family.

setFontWeight(fontWeight) ​

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

Set the font weight for the widget.

Returns — void

typescript
chartspire.setFontWeight('bold')
chartspire.setFontWeight(600)

getFontWeight() ​

typescript
() => string

Returns — Current font weight as a string (numeric weights are stringified, for example '600').

Locale and timezone ​

Locale and timezone are shared across all charts in the widget. Locale state is isolated between separate ChartSpire instances.

setLocale(locale) ​

typescript
(locale: string) => void

Set the widget language for all current and future charts and UI in this instance.

Parameters

Returns — void

getLocale() ​

typescript
() => string

Returns — Current widget language.

setTimezone(timezone) ​

typescript
(timezone: string) => void

Set the widget timezone for all charts.

Returns — void

getTimezone() ​

typescript
() => string

Returns — Current widget timezone.

Charts and multichart ​

Chart panes are identified by ChartID, exported from @chartspire/ui. ChartSpire assigns fixed IDs from chart1 through chartN, where N is your multiChartLimit (up to 16). You cannot define custom IDs; use getAllChartIds() for every ID in range.

typescript
import type { ChartID } from '@chartspire/ui'

interface ChartID {
  id: string;
}

getChart(chartId) ​

typescript
(chartId: ChartID) => ChartApi | null

Returns — The Chart API for a specific chart, or null if that chart is not mounted.

getActiveChart() ​

typescript
() => ChartApi | null

Returns — The Chart API for the active chart, or null if it is not mounted.

isActiveChart(chartId) ​

typescript
(chartId: ChartID) => boolean

Returns — Whether the given chart is the active chart.

setActiveChart(chartId) ​

typescript
(chartId: ChartID) => void

Set the active chart. No-op (error logged) if the id is outside the configured range.

Returns — void

getMultiChart() ​

typescript
() => number

Returns — Current number of displayed (mounted) charts. Grid preset changes are UI-only; there is no setter.

getAllChartIds() ​

typescript
() => ChartID[]

Returns — All chart IDs available for the configured multiChartLimit (not only mounted panes).

getVisibleChartIds() ​

typescript
() => ChartID[]

Returns — Chart IDs for panes currently mounted in the active grid.

typescript
chartspire.getVisibleChartIds().forEach((id) => {
  chartspire.getChart(id)?.scrollToRealTime()
})

Lifecycle ​

destroy() ​

typescript
() => void

Dispose the widget: unmount charts, dispose session runtime, release DataFeed ownership for this embed, and clear the container.

Returns — void

Safe to call more than once. Destroying one embed does not close a shared DataFeed socket while other embeds still own it. Host storage/watchlist callbacks and the DataFeed registry are process-global and are not cleared by destroy().

Copyright © 2026 ChartSpire