API Reference

This page is a compact map of the public Orchid Charts API. Begin with Getting started if you have not rendered a chart yet.

Imports

import {
  LineChart,
  BarChart,
  ScatterChart,
  MixedChart,
  BubbleChart,
  PieChart,
  DonutChart,
  PercentageChart,
  RadarChart,
  PolarAreaChart,
  HeatmapChart,
  TimesheetChart,
} from "@orchidsoftware/charts";

import "@orchidsoftware/charts/style.css";

Each definition exposes make(parent), where parent is a CSS selector or an Element. Configuration methods return the same builder, and render() mounts the chart synchronously. The host and its chart/theme styles must be ready; see Stylesheet readiness.

Common Chart Methods

Charts with a legend also provide legend(false). Categorical legends share one bottom placement with color dots beside their labels and whole-item wrapping.

Series Data

Line, bar, scatter, bubble, radar, pie, donut, percentage, and polar area charts use dataset():

chart
  .labels(["Jan", "Feb", "Mar"])
  .dataset("Actual", [42, 48, 57])
  .dataset("Plan", [45, 50, 55])
  .dataset("Previous", [38, 41, 49], "#94a3b8");

Accepted forms are:

dataset(values)
dataset(values, color)
dataset(values, callback)
dataset(name, values)
dataset(name, values, color)
dataset(name, values, callback)
dataset(input, callback?)

A numeric dataset input has this shape:

{
  name: "Revenue",       // optional
  values: [42, 48, 57],
  color: "#2563eb",      // optional
  opacity: 0.8,           // optional, 0–1
  formatValue(value, context) { return String(value); } // optional
}

labels() is optional. When omitted, Orchid Charts generates positional labels. Multiple series require a unique, non-empty name for each dataset. A single series can omit its name.

Cartesian Methods

Line, bar, scatter, bubble, and mixed charts provide:

LineChart

import { LineChart } from "@orchidsoftware/charts";

LineChart.make(parent)
  .labels(labels)
  .dataset(name, values)
  .smooth()
  .gradient()
  .render();

Line-specific methods: smooth(enabled?), dots(visible), dotSize(pixels), line(visible), area(enabled?), gradient(enabledOrOptions?), and strokeWidth(pixels).

Gradient options are { fromOpacity?, toOpacity? }.

See Line charts for examples of every line method.

BarChart

import { BarChart } from "@orchidsoftware/charts";

BarChart.make(parent)
  .labels(labels)
  .dataset(name, values)
  .horizontal()
  .stacked()
  .render();

Bar-specific methods: horizontal(enabled?), stacked(enabled?), and radius(pixels).

See Bar charts for grouped, horizontal, and stacked examples.

ScatterChart

import { ScatterChart } from "@orchidsoftware/charts";

ScatterChart.make(parent)
  .dataset("Results", [{ x: 12, y: 38 }])
  .render();

Values may be { x, y } points or numbers. A number uses its array index as x. Scatter charts also provide dots(visible).

See Scatter charts for point and dataset examples.

BubbleChart

import { BubbleChart } from "@orchidsoftware/charts";

BubbleChart.make(parent)
  .dataset("Accounts", [{ x: 12, y: 38, r: 8 }])
  .render();

Every bubble is { x, y, r }. Bubble charts also provide dots(visible). Automatic coordinate domains account for circle bounds while preserving r in CSS pixels.

See Bubble charts for radius and dataset guidance.

MixedChart

import { MixedChart } from "@orchidsoftware/charts";

MixedChart.make(parent)
  .labels(labels)
  .bar("Actual", actual)
  .line("Plan", plan)
  .scatter("Events", events)
  .render();

Use bar(name, values, colorOrCallback?), line(...), and scatter(...). gradient(enabledOrOptions?) applies to line datasets.

See Mixed charts for each dataset type and its methods.

Composition and Radial Charts

These charts use numeric labels() and dataset() data. They also provide formatLabel(formatter) and formatValue(formatter).

maxSlices() keeps the largest categories and combines the remainder.

Each type has its own guide: Pie, donut, percentage, radar, and polar area.

HeatmapChart

import { HeatmapChart } from "@orchidsoftware/charts";

HeatmapChart.make(parent)
  .range(new Date("2026-01-01T00:00:00Z"), new Date("2026-12-31T00:00:00Z"))
  .points({ "2026-08-28": 4, "2026-08-29": 9 })
  .countLabel("contributions")
  .radius(2)
  .render();

The tooltip callback provides formatDate(formatter) and formatValue(formatter).

See Calendar heatmaps for range, color scale, and tooltip examples.

TimesheetChart

import { TimesheetChart } from "@orchidsoftware/charts";

TimesheetChart.make(parent)
  .range("2026-09-01", "2026-09-12")
  .task("Design", "2026-09-01", "2026-09-03")
  .task({
    label: "Build",
    start: "2026-09-03",
    end: "2026-09-08",
    group: "Engineering",
    color: "#2563eb",
  })
  .render();

The tooltip callback provides formatDate(formatter) and formatDuration(formatter).

Timesheet dates accept Date, milliseconds, YYYY-MM-DD, or date-time strings with an explicit timezone.

See Timesheet charts for task, range, and formatting examples.

Scoped Customization

Callbacks expose methods only for the item they configure:

import { LineChart } from "@orchidsoftware/charts";

LineChart.make("#chart")
  .dataset("Actual", values, (dataset) => {
    dataset
      .color("#2563eb")
      .opacity(0.9)
      .formatValue((value) => `${value}k`)
      .smooth()
      .gradient()
      .dots(true)
      .dotSize(5)
      .line(true)
      .area(false)
      .strokeWidth(3);
  })
  .render();

• Every dataset callback: color(), opacity(), formatValue().
• Line dataset callback: gradient(), smooth(), dots(), dotSize(), line(), area(), strokeWidth().
• Bar dataset callback: radius().
• Y-axis callback: position("left" | "right"), formatValue().
• Series tooltip callback: formatLabel(), formatValue().
• Marker callback: color(), width(), opacity(), lineStyle(), dash(), labelPosition(), labelColor(), includeInDomain(), formatLabel().
• Region callback: color(), opacity(), labelPosition(), labelColor(), includeInDomain(), formatLabel().

Callbacks run while the builder is being configured; do not keep their scoped objects for later use.

Runtime API

render() returns a chart with the same lifecycle for every definition:

render() and update() validate supplied CSS colors in the host's current style context. An unresolved var(--name) without a fallback throws a TypeError before changing the host content or mounted chart. After the styles are ready, the caller can retry the same method; the library does not schedule a retry.

See Updates and interaction for the mounted lifecycle and Exporting SVG for serialization and download.

TypeScript

Type declarations ship with the package. Each named definition returns a chart-specific builder, so autocomplete shows only methods that can affect that chart. Public input, update, point, and selection types can also be imported from @orchidsoftware/charts.

Compatibility and Stability

The current 0.x API can change between releases. Starting with 1.0, semantic versioning covers documented builders and runtime methods, accepted data shapes, TypeScript declarations, selection and point payloads, and documented CSS variables. Incompatible changes to that surface require a major release.

The generated SVG structure, internal classes, diagnostic data attributes, and exact pixel geometry are implementation details. Use the public lifecycle and CSS variables to integrate and theme charts.

The browser runtime targets current evergreen Chromium, Firefox, and Safari with native ESM and modern SVG/CSS. Node.js 22.12 or later is the supported installation and build toolchain; rendering requires a browser DOM. Importing the module during SSR is supported, but call render() only after mounting.

Numeric inputs must be finite numbers. Derived axis spans, tick steps, and composition totals must also be representable as finite JavaScript numbers; values outside that range raise an error before replacing a mounted chart.

Line and Bar preserve the supplied values without automatic aggregation or downsampling. There is no universal point-count or rendering-time guarantee. Prepare large inputs using the aggregation and windowing recipes.