---
id: "packages/active-charts/all-exports/base-chart-props"
title: "Base chart props"
description: "BaseChartProps, CartesianChartProps, CategoricalChartProps, ChartEvents and 10 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/base-chart-props"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:base-chart-props"
---

# Base chart props

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## Types

**BaseChartProps**

```ts
interface BaseChartProps extends ChartEvents {
  height: number;
  width?: number;
  className?: string;
  dir?: 'ltr' | 'rtl';
  locale?: ChartPresentation;
  t?: ChartTranslateFn;
  accessibility?: AccessibilityOptions;
  colors?: string[];
  tooltip?: FeatureOption<TooltipOptions>;
  contextMenu?: FeatureOption<ChartContextMenuOptions<never>>;
  animation?: FeatureOption<Omit<AnimationOptions, 'replay'>>;
  events?: ChartEvents;
  ref?: Ref<ChartHandle>;
}
```

Every chart component in `active-charts` extends this interface. Props
that are not universally meaningful (series config, axis config, specific
data shapes) live on the archetype mixins below.

Consumers can set many of these via {@link ChartDefaultsContext} — the
`useChartDefaults` hook merges context defaults with explicit props, with
explicit props always winning.

**CartesianChartProps**

```ts
interface CartesianChartProps<
  TDatum = Record<string, unknown>,
> extends Omit<BaseChartProps, 'contextMenu' | 'events'> {
  data: TDatum[];
  xKey: string;
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<
      CartesianPoint<TDatum>,
      'copy' | 'zoom' | 'series' | 'export'
    >
  >;
  events?: ChartEvents & ChartSelectionEvents<TDatum>;
}
```

Cartesian charts: data is a flat array of rows keyed by field name.

The one Cartesian contract: every Cartesian wrapper (line,
area, bar, histogram, scatter, candlestick, ohlc, waterfall, range-area,
range-bar, box-plot, dumbbell, lollipop) derives its props from it as
`Omit<CartesianChartProps<TDatum>, 'xKey' | …>`, plus
`ChartSelectionProps`: the discriminated `xKey`/`xAxis` pair
replaces the plain `xKey`, and a family leaves out only what it does not
read. The heatmap reuses the row shape with its own matrix
contract; the timeline takes `BaseChartProps` directly.

It holds the {@link BaseChartProps} members plus `data`, `xKey` (the
x-axis field), the context menu on a {@link CartesianPoint} and the
`events` bundle with the selection events.

**Y-axis fields live on each series item** (`series[i].yKey`) because a
Cartesian chart may carry multiple y-series on the same x-axis.
Single-series wrappers additionally accept a top-level `yKey` as a
shorthand — see the individual chart component for its exact shape.

Series config and axis config are chart-specific and live on the
component itself.

**CategoricalChartProps**

```ts
interface CategoricalChartProps<
  TDatum = Record<string, unknown>,
> extends BaseChartPropsWithout<
  'contextMenu' | 'onZoomChange' | 'tooltip' | 'animation' | 'accessibility'
> {
  accessibility?: StandaloneAccessibilityOptions;
  tooltip?: StandaloneTooltipOption;
  animation?: StandaloneAnimationOption<'type'>;
  data: TDatum[];
  valueKey: string;
  categoryKey: string;
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<
      CategoricalSlice<TDatum>,
      'copy' | 'series' | 'export'
    >
  >;
}
```

Categorical charts: one value per slice/segment. Pie, nightingale,
radial-bar, funnel, radar.

The universal field names are `valueKey` and `categoryKey` — NEVER
`angleKey`, `key`, `nameKey`, `labelKey`, etc.

**ChartEvents**

```ts
interface ChartEvents {
  onReady?: () => void;
  onAnimationComplete?: (event: AnimationCompleteEvent) => void;
  onExportComplete?: (result: ChartExportResult) => void;
  onExportError?: (format: ChartExportFormat, error: unknown) => void;
  onZoomChange?: (
    startFraction: number,
    endFraction: number,
    yStartFraction?: number,
    yEndFraction?: number,
  ) => void;
  onLegendChange?: (change: ChartLegendChange) => void;
}
```

Unified event model — all chart-level callbacks live here. High-level
wrappers accept these either individually (spread onto the component) or
bundled as a single `events` prop. ChartOptions MUST NOT duplicate these.

Not every event fires on every chart — zoom events only fire on charts
that support zoom, legend events only when the legend is enabled, etc.

**ChartExportHandle**

```ts
interface ChartExportHandle {
  exportAsPng: (
    filename?: string,
    scale?: number,
    options?: {
      backgroundColor?: string;
      includeLegend?: boolean;
      report?: ChartExportReport;
      fonts?: ChartExportFonts | 'inherit';
      download?: boolean;
    },
  ) => Promise<ChartExportResult>;
  exportAsSvg: (
    filename?: string,
    options?: {
      includeLegend?: boolean;
      report?: ChartExportReport;
      fonts?: ChartExportFonts | 'inherit';
      download?: boolean;
    },
  ) => Promise<ChartExportResult>;
  exportAsCsv: (
    filename?: string,
    columns?: string[],
    options?: {
      download?: boolean;
    },
  ) => Promise<ChartExportResult>;
  exportAsPdf: (
    filename?: string,
    options?: {
      pageSize?: 'a4' | 'letter' | [number, number];
      orientation?: 'portrait' | 'landscape';
      scale?: number;
      backgroundColor?: string;
      includeLegend?: boolean;
      margin?: number;
      report?: ChartExportReport;
      fonts?: ChartExportFonts | 'inherit';
      download?: boolean;
    },
  ) => Promise<ChartExportResult>;
  getSvgElement: () => SVGSVGElement | null;
  getContainerElement: () => HTMLDivElement | null;
}
```

The imperative handle every chart exposes via `ref`: exports and element
access. A chart with a data-range zoom (`<Chart>` and the Cartesian
wrappers) exposes the wider {@link ChartHandle}, which adds `setZoom`;
every other family (pie, heatmap, the categorical, hierarchical, graph and
scalar families, timeline, sparkline) exposes this one.

**Every export resolves with the file it produced** (W11, ADR-105): one
call captures once, and the {@link ChartExportResult} names that file
(`format`, `filename` with its extension, `blob`, `downloadStarted`,
`warnings`). With `download` absent or `true` the same Blob is handed to
the browser; with `download: false` it is only returned. An export
rejects with an error when no file could be produced
(`onExportComplete(result)` and `onExportError` report the same
outcome). An image export waits until the chart is still, so it never
captures an animation half-way, whether it downloads or not. `includeLegend` applies wherever the
chart paints a legend (the Cartesian charts, pie, funnel, radar, radial
bar, nightingale), which the export lays on the painted side; the other
families have no legend to include. The context menu runs the same
exports (LAB-AT12, LAB-AT18).

**ChartExportReport**

```ts
interface ChartExportReport {
  title?: string;
  subtitle?: string;
  caption?: string;
}
```

Text the host supplies for a report-style export (W11): a title and a
subtitle above the chart, a caption below it. The chart never writes
these words itself.

**ChartHandle**

```ts
interface ChartHandle extends ChartExportHandle {
  setZoom: (
    startFraction: number,
    endFraction: number,
    animated?: boolean,
    yStartFraction?: number,
    yEndFraction?: number,
  ) => void;
}
```

The handle of a chart with a data-range zoom: `<Chart>` and the Cartesian
wrappers. {@link ChartExportHandle} plus `setZoom`.

**FeatureOption**

```ts
type FeatureOption<T> = T | boolean;
```

`T | boolean` — the canonical feature-toggle pattern.

- `true`: enable the feature with defaults
- `false`: disable the feature
- object: enable the feature with explicit configuration

Applies uniformly to tooltip, contextMenu, animation, legend, crosshairs,
zoom, navigator, sync, selection, colorLegend and most dataLabels.
`drilldown`, `sizeLegend`, `zoomControls` and the gauge's `replay` stay
plain booleans on purpose: there is nothing to configure beyond on or off.

**GraphChartProps**

```ts
interface GraphChartProps<
  TNodeExtra extends Record<string, unknown> = Record<string, unknown>,
  TLinkExtra extends Record<string, unknown> = Record<string, unknown>,
> extends BaseChartPropsWithout<
  | 'contextMenu'
  | 'onZoomChange'
  | 'onLegendChange'
  | 'animation'
  | 'tooltip'
  | 'accessibility'
> {
  accessibility?: StandaloneAccessibilityOptions;
  tooltip?: StandaloneTooltipOption;
  animation?: InteractionAnimationOption;
  nodes: NodeDatum<TNodeExtra>[];
  links: LinkDatum<TLinkExtra>[];
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<
      SankeyElement<TNodeExtra, TLinkExtra>,
      'copy' | 'export'
    >
  >;
}
```

Graph charts: nodes + links. Currently Sankey only.

**HierarchicalChartProps**

```ts
interface HierarchicalChartProps<
  TExtra extends Record<string, unknown> = Record<string, unknown>,
> extends BaseChartPropsWithout<
  | 'contextMenu'
  | 'onZoomChange'
  | 'onLegendChange'
  | 'animation'
  | 'tooltip'
  | 'accessibility'
> {
  accessibility?: StandaloneAccessibilityOptions;
  tooltip?: StandaloneTooltipOption;
  animation?: StandaloneAnimationOption<'type'>;
  data: HierarchyNode<TExtra>;
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<HierarchyElement<TExtra>, 'copy' | 'export'>
  >;
}
```

Hierarchical charts: tree-structured data. Treemap, sunburst, org chart.
Data is a single root {@link HierarchyNode} with nested children.

**HierarchyNode**

```ts
interface HierarchyNode<
  TExtra extends Record<string, unknown> = Record<string, unknown>,
> {
  label: string;
  value?: number;
  children?: HierarchyNode<TExtra>[];
  color?: string;
  colorValue?: number | null;
  id?: string;
  meta?: TExtra;
}
```

Unified hierarchy node — used by treemap, sunburst, and org chart.

**LinkDatum**

```ts
interface LinkDatum<
  TExtra extends Record<string, unknown> = Record<string, unknown>,
> {
  id?: string;
  source: string;
  target: string;
  value: number;
  color?: string;
  meta?: TExtra;
}
```

Unified graph link — used by Sankey. Source and target are **node ids**,
not array indices.

**NodeDatum**

```ts
interface NodeDatum<
  TExtra extends Record<string, unknown> = Record<string, unknown>,
> {
  id: string;
  label?: string;
  value?: number;
  color?: string;
  meta?: TExtra;
}
```

Unified graph node — used by Sankey (and any future graph chart).
Sankey is **id-based** (not index-based) — `LinkDatum.source` / `.target`
reference `NodeDatum.id`.

**ScalarChartProps**

```ts
interface ScalarChartProps extends BaseChartPropsWithout<
  | 'colors'
  | 'tooltip'
  | 'contextMenu'
  | 'onZoomChange'
  | 'onLegendChange'
  | 'animation'
  | 'accessibility'
> {
  contextMenu?: FeatureOption<ChartContextMenuOptions<unknown, 'export'>>;
  accessibility?: StandaloneAccessibilityOptions;
  animation?: ScalarAnimationOption;
  value: number;
  min?: number;
  max?: number;
  valueSemantics?: ChartValueSemantics;
  scale?: ScalarScaleOption;
  target?: ScalarTarget;
}
```

Scalar charts: a single (or few) numeric value. Gauge, linear gauge,
bullet. No array data, no keys — just a number with optional bounds/bands.

`max` is optional because gauge-style charts carry their own sensible
default (radial gauge: `100`). When omitted, the individual chart
component documents the effective default on its own props interface.