---
id: "packages/active-charts"
title: "active-charts"
description: "Charts of every common family on D3 mathematics and its own React components, with one API contract across families."
url: "/packages/active-charts"
locale: "en"
revision: "447b27abe3f9c995"
---

# active-charts

`@workspace/active-charts` draws 28 chart families with its own React components over D3
mathematics: no chart engine and no UI framework. Every family follows one contract
(`BaseChartProps` plus the props of its archetype), so a tooltip, a legend, a context menu,
selection, export and keyboard navigation work the same way in each.

**Example: A first chart**

Client: Runs entirely in your browser. Source: `examples/charts/first-chart.tsx`.

```tsx
// apps/docs/examples/charts/first-chart.tsx
'use client';

import {
  ChartDefaults,
  englishChartTranslator,
  LineChart,
} from '@workspace/active-charts';

const data = [
  {date: new Date(Date.UTC(2026, 0, 2)), price: 100.5},
  {date: new Date(Date.UTC(2026, 0, 5)), price: 101.2},
  {date: new Date(Date.UTC(2026, 0, 6)), price: 102.0},
  {date: new Date(Date.UTC(2026, 0, 7)), price: 101.4},
  {date: new Date(Date.UTC(2026, 0, 8)), price: 103.1},
  {date: new Date(Date.UTC(2026, 0, 9)), price: 104.0},
];

/** The smallest chart: a presentation and a translator once, a line per series. */
export default function FirstChart() {
  return (
    <ChartDefaults locale="en-GB" t={englishChartTranslator}>
      <LineChart
        data={data}
        xKey="date"
        yKey="price"
        name="Price"
        // The x values are calendar days, not moments in time.
        xAxis={{temporalSemantic: 'calendarDate'}}
        height={260}
      />
    </ChartDefaults>
  );
}
```

## Families

| Archetype | Families |
| --- | --- |
| Cartesian | Line, Area, Bar, Histogram, Scatter (and bubble), Candlestick, OHLC, Range area, Range bar, Box plot, Dumbbell, Lollipop, Waterfall, Heatmap |
| Categorical | Pie and donut, Funnel, Radial bar, Nightingale, Radar |
| Hierarchy and flow | Treemap, Sunburst, Sankey, Organisation chart, Timeline |
| Scalar | Gauge, Linear gauge, Bullet, Sparkline (outside the contract by design) |

`<Chart>` with a `ChartOptions` object is the low-level form and the combination chart for any mix
of series types. Every family is drawn on [Families](/packages/active-charts/families).

## What it does

- **Interaction**: tooltips (single, shared, split), an interactive legend, hover highlighting,
  crosshairs, zoom and pan, a navigator, linked views in a `<SyncGroup>`.
- **Selection and activation** of items by pointer, touch and keyboard, controlled or not.
- **Export**: PNG, SVG, CSV and PDF through the imperative `ChartHandle`.
- **Information paths**: a data table per chart, keyboard navigation per archetype, announcements
  and forced-colours styles.
- **Truth-preserving reduction** of long series, and opt-in calendar grouping.
- **Unavailable states** for data a chart cannot draw truthfully.

## What it does not do

- **No language of its own.** Words go through the translator you pass (`t`);
  `englishChartTranslator` is the package's English. The presentation (`locale`) is required.
- **No colours of its own beyond a default.** Colours come from CSS tokens your host sets
  (`--chart-*` and the semantic surface and text tokens); the package has light and dark defaults
  when you set none. There is no theme provider.
- **No data fetching.** You pass the rows.

## What your application provides

- A presentation and a translator, per chart or once on `<ChartDefaults>`.
- Optionally the CSS tokens of your brand; this site uses active-ui's `--chart-*` tokens, so charts
  match the components beside them without a second visual system.
- A diagnostics sink on `<ChartDefaults diagnostics>`, if you want warnings outside the console.
- For PDF export, the optional `jspdf` and `svg2pdf.js`.

## Dependencies

`@workspace/active-format` and `@workspace/active-helpers` (owners that come along), the D3 modules
it computes with, `@base-ui/react` for its menus, `date-fns` and `@date-fns/tz`. `react` and
`react-dom` 19 are peers.

## Next

- [Getting started](/packages/active-charts/getting-started)
- [Families](/packages/active-charts/families)