OrbCharts Class

OrbCharts is the entry point to the library. You create an instance from a DOM container and an options object, then use its methods to dynamically update data, Encoding, Plugins, Theme, and size—and release resources when you no longer need it.

import { OrbCharts } from '@orbcharts/core'
 
const chart = new OrbCharts(element, options)

Constructor

new OrbCharts(element: HTMLElement | Element, options?: PartialChartOptions)

All fields of PartialChartOptions are optional:

interface PartialChartOptions {
  size?:     SizeConfig
  theme?:    DeepPartial<Theme>
  data?:     RawData
  encoding?: DeepPartial<Encoding>
  plugins?:  PluginEntity[]
}

import { OrbCharts } from '@orbcharts/core'
import type { RawData } from '@orbcharts/core'
import { GridPlot } from '@orbcharts/plugin-basic'
 
const data: RawData = [
  { series: 'A', category: 'Q1', value: 30 },
  { series: 'A', category: 'Q2', value: 55 },
]
 
const chart = new OrbCharts(document.querySelector('#chart')!, {
  data,
  theme: { colorScheme: 'dark' },
  plugins: [new GridPlot({ Bar: {}, CategoryAxis: {}, ValueAxis: {} })],
})

Tip: theme and encoding accept a DeepPartial, so you only override the fields you want to change; the rest keep their defaults (deep merge).

Data

setData

setData(data: RawData): void

Fully replaces the chart's raw data and re-renders. For the structure of RawData and each dimension's format, see Data formats overview.

chart.setData([
  { series: 'A', value: 30 },
  { series: 'B', value: 70 },
])

Encoding

Encoding determines how raw-data fields map to the chart's dimensions (dataset, series, category, value, etc.), and lets you specify sorting and aggregation. See Encoding for the full field reference.

updateEncoding

updateEncoding(patch: DeepPartial<Encoding>): void

Partially updates the Encoding, deep-merged with the current value. Ideal for tweaking a single setting.

// Only remap the value field to "amount"; everything else stays the same
chart.updateEncoding({ value: { from: 'amount' } })

forceReplaceEncoding

forceReplaceEncoding(full: Encoding): void

Replaces the current settings entirely with a complete Encoding object. Fields you omit do not keep their old values.

getEncoding

getEncoding(): Readonly<Encoding>

Returns the currently effective Encoding (read-only).

Plugins

Plugins do the actual rendering. For operations common to all Plugins, see Plugin API.

setPlugins

setPlugins(plugins: PluginEntity[]): void

Replaces all current Plugins with a new array.

import { GridPlot, Tooltip } from '@orbcharts/plugin-basic'
 
chart.setPlugins([new GridPlot({ Line: {}, CategoryAxis: {}, ValueAxis: {} }), new Tooltip()])

addPlugin

addPlugin(plugin: PluginEntity): void

Adds a single Plugin without affecting the other existing Plugins.

import { Legend } from '@orbcharts/plugin-basic'
 
chart.addPlugin(new Legend())

removePlugin

removePlugin(id: string): void

Removes a Plugin by its id.

chart.removePlugin('Legend')

Theme

updateTheme

updateTheme(patch: DeepPartial<Theme>): void

Partially updates the theme, deep-merged with the current value. See Theme for the full structure.

chart.updateTheme({ colorScheme: 'dark' })

forceReplaceTheme

forceReplaceTheme(full: Theme): void

Replaces the current theme entirely with a complete Theme object.

getTheme

getTheme(): Readonly<Theme>

Returns the currently effective theme (read-only).

Sizing

resize

resize(sizeConfig: SizeConfig): void

Sets the chart size and auto-resize behavior.

interface SizeConfig {
  width:  number | 'auto'
  height: number | 'auto'
  resizeDebounce: number
}

// Fixed width, auto height, with a shorter debounce
chart.resize({ width: 800, height: 'auto', resizeDebounce: 30 })

Tip: 'auto' follows the container's size, so the container itself must have an explicit width and height. Sizing and the container mechanism are the most common beginner pitfall.

Lifecycle

destroy

destroy(): void

Releases all resources, removes event listeners, and cleans up its Plugins as well.

chart.destroy()

Tip: On component unmount (React's useEffect cleanup, Vue's onUnmounted), always call chart.destroy() to avoid memory leaks and dangling event subscriptions.

The context property

chart.context: ChartContext

context exposes the chart's internal RxJS streams (such as event$, encoding$, theme$) and root nodes (root, svg, canvas) for advanced subscription and integration. For event usage see Events; for the full list of streams see TypeScript Types.

Related

• Encoding — field mapping, sorting, and aggregation
• Theme — colors and light/dark mode
• Plugin API — operations common to all Plugins
• Events — listening to and triggering chart events
• TypeScript Types — the full list of types