Base chart props
BaseChartProps, CartesianChartProps, CategoricalChartProps, ChartEvents and 10 more: generated from the source of active-charts.
Exported by @workspace/. Generated from the package source; part of the index of every export.
Types#
Every chart component in active- 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 Chart — the use hook merges context defaults with explicit props, with explicit props always winning.
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>;
}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<Cartesian, plus Chart: the discriminated x/x pair replaces the plain x, 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 Base directly.
It holds the Base members plus data, x (the x-axis field), the context menu on a Cartesian and the events bundle with the selection events.
Y-axis fields live on each series item (series[i].) because a Cartesian chart may carry multiple y-series on the same x-axis. Single-series wrappers additionally accept a top-level y 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.
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>;
}Categorical charts: one value per slice/segment. Pie, nightingale, radial-bar, funnel, radar.
The universal field names are value and category — NEVER angle, key, name, label, etc.
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'
>
>;
}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.
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;
}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 Chart, which adds set; 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 Chart names that file (format, filename with its extension, blob, download, 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 (on and on 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. include 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).
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;
}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.
interface ChartExportReport {
title?: string;
subtitle?: string;
caption?: string;
}The handle of a chart with a data-range zoom: <Chart> and the Cartesian wrappers. Chart plus set.
interface ChartHandle extends ChartExportHandle {
setZoom: (
startFraction: number,
endFraction: number,
animated?: boolean,
yStartFraction?: number,
yEndFraction?: number,
) => void;
}- Type
type FeatureOption<T> = T | boolean;
T | boolean — the canonical feature-toggle pattern.
true: enable the feature with defaultsfalse: 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, size, zoom and the gauge's replay stay plain booleans on purpose: there is nothing to configure beyond on or off.
Graph charts: nodes + links. Currently Sankey only.
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'
>
>;
}Hierarchical charts: tree-structured data. Treemap, sunburst, org chart. Data is a single root Hierarchy with nested children.
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'>
>;
}Unified hierarchy node — used by treemap, sunburst, and org chart.
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 graph link — used by Sankey. Source and target are node ids, not array indices.
interface LinkDatum<
TExtra extends Record<string, unknown> = Record<string, unknown>,
> {
id?: string;
source: string;
target: 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) — Link / . reference Node.
interface NodeDatum<
TExtra extends Record<string, unknown> = Record<string, unknown>,
> {
id: string;
label?: string;
value?: number;
color?: string;
meta?: TExtra;
}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.
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;
}