Core Concepts

This page explains the design ideas behind OrbCharts. Once you understand these concepts, you can freely combine data, Plugins, and Theme to draw any chart.

Data flow

OrbCharts is data-driven: you provide raw data, and the library runs a series of transformations that ultimately output SVG. The flow is as follows:

RawData ──(Encoding field mapping)──▶ ModelData ──(Plugin computes coordinates + Theme applies colors)──▶ SVG

1. RawData: the raw data array you provide.
2. Encoding: maps your raw fields to the fields OrbCharts uses internally (for example which field is the value, and whether to aggregate).
3. ModelData: the standardized data after mapping and computation. This is also the structure you receive in events (such as click or Tooltip).
4. Plugin + Theme: the Plugin computes the coordinates and shapes for each record, the Theme determines colors, and the result is rendered as SVG.

The 5 data formats

OrbCharts uses ModelType to distinguish the "shape" of your data. Each data format corresponds to different Plugins:

Tip: First figure out "what shape is my data", then pick the matching format and Plugin. See Data Formats Overview for the full reference.

Plugin and Layer

• A Plugin is a chart engine; a single Plugin can draw multiple chart types. For example PartitionPlot can draw pie, rose, and bubble charts.
• A Layer is a single visual element, such as a slice, a line, or an axis. A Plugin is composed of multiple Layers.

The Layer names you list in the Plugin parameters determine which Layers are shown:

new PartitionPlot({ Pie: {} })   // shows only the Pie layer → pie chart

Tip: The Layer display mechanism, dynamic toggling (show, hide, showOnly), and shared parameter types are detailed in Plugin API.

Theme

Theme controls the colors and light/dark mode of the entire chart. It is decoupled from data and Plugins—switching the Theme requires no changes to data or Plugins. The ColorType values commonly seen in Layer parameters (such as 'data', 'primary') point to colors defined in the Theme.

const chart = new OrbCharts(element, {
  data,
  theme: { colorScheme: 'dark' },
  plugins: [/* ... */],
})

Tip: For the full reference on color palettes, light/dark mode, and ColorType, see Theme.

Sizing and container mechanism

OrbCharts renders charts into the container DOM you specify. The size option defaults to:

{ width: 'auto', height: 'auto', resizeDebounce: 50 }

'auto' means the chart fills its container automatically and re-renders when the container size changes (resizeDebounce is the debounce delay for re-rendering, in milliseconds).

Note: Because the default is 'auto', the container DOM must have an explicit width and height, otherwise the chart has no space to fill and will not be visible. This is the most common beginner issue.

<div id="chart" style="width: 600px; height: 400px;"></div>

After creation, you can adjust the size anytime with chart.resize(sizeConfig):

chart.resize({ width: 800, height: 500 })

Creating and updating a chart

The OrbCharts constructor is:

new OrbCharts(element, options?)

options is a PartialChartOptions, where all fields are optional:

interface PartialChartOptions {
  size?: SizeConfig        // size (defaults to 'auto')
  theme?: PartialTheme     // theme
  data?: RawData           // raw data
  encoding?: Encoding      // field mapping
  plugins?: Plugin[]       // list of Plugins
}

After creation, you can update the chart dynamically without recreating it:

Related

• Your First Chart — combine these concepts into an actual chart
• Data Formats Overview — the 5 data formats explained
• Plugin API — Layer display and parameter operations
• Theme — colors and theming