` (LAB-AT21). | | `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished. Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. | | `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. | | `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). | | `onItemActivate` | `((item: ChartSeriesItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). | | `onLegendChange` | `((change: ChartLegendChange) => void)` | no | Fired once for every legend change the chart applies: a hide, a show, an isolation or a show-all, from the built-in legend (click, key, double click, double tap), its menu, or `useChartLegend()`. The change names the entry and its target by identity and lists every hidden target after it. A refused action (the last visible target, `legend.interactive: false`) changes nothing and reports nothing. | | `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests. Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness. A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance). **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. | | `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartSeriesItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. | | `paint` | `DatumPaintResolver<DatumFill, TDatum>` | no | A stage's own fill, by a rule over its row (T1, the contract of BC-P1, ADR-092): the one stage below target in the negative role. Returns `{fill}` or `undefined` for the stage's palette colour; paint only. The stage IS its legend category, so its legend key, its tooltip swatch, its label's contrast surface and its export all show the painted fill; forced colours override it. The context's `seriesId` is `'funnel'` and its `seriesName` the chart's `name`. See {@link DatumPaintResolver}. | | `ref` | `Ref<ChartExportHandle>` | no | Imperative handle: exports and element access. A family built on this type has no data-range zoom, so its handle has no `setZoom`. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). | | `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. | | `selection` | `FeatureOption<ChartSelectionOptions>` | no | Item selection. `true` = single selection keyed by the default key. | | `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). | | `tooltip` | `StandaloneTooltipOption<never>` | no | Tooltip of the slice under the pointer: `enabled`, `renderer`, `valueFormatter` and `style` (ADR-082, LAB-AT17). | | `valueSemantics` | `ChartValueSemantics` | no | What the stage values mean (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The stage labels, the tooltip, the data table and the announcement write each value in it; a stage's share of the first stays a percentage. The label's own `formatter` or `format` (and `tooltip.valueFormatter`) still wins; without a declaration the chart presentation's number applies. CSV and Copy value keep the raw number. | | `width` | `number` | no | Optional fixed width in pixels. Default: fill container. | ## Types **FunnelChartProps** ```ts interface FunnelChartProps<TDatum extends ChartDatum = ChartDatum> extends Omit<CategoricalChartProps<TDatum>, 'events'>, ChartSelectionProps<TDatum, ChartSeriesItem<TDatum>> { events?: NonNullable<CategoricalChartProps<TDatum>['events']> & ChartSelectionEvents<TDatum, ChartSeriesItem<TDatum>>; name?: string; gap?: number; dataLabels?: FunnelDataLabelOptions | boolean; legend?: LegendOptions | boolean; legendLink?: ChartLegendLink; minSegmentWidthFraction?: number; valueSemantics?: ChartValueSemantics; paint?: DatumPaintResolver<DatumFill, TDatum>; } ``` Props for {@link FunnelChart}. Extends {@link CategoricalChartProps} to join the wrapper contract. Chart-specific fields (`gap`, `dataLabels`, `legend`, `minSegmentWidthFraction`) remain on this interface. Entrance animation: defaults to `stagger-segments` (sequential per-segment fade+slide). `fade` and `none` are also supported. Hover-transitions (100–150ms opacity) are retained as interaction feedback and fall below the WCAG 2.3.3 threshold for reduced-motion concerns; the global media query in `accessibility.css` suppresses them defensively under `prefers-reduced-motion: reduce`.

--- id: "packages/active-charts/all-exports/funnel-chart" title: "FunnelChart" description: "FunnelChart, FunnelChartProps: generated from the source of active-charts." url: "/packages/active-charts/all-exports/funnel-chart" locale: "en" revision: "g0mvjxwj5c-88bdbe1c:funnel-chart" --- # FunnelChart Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports). ## `FunnelChart` | Prop | Type | Required | Description | | --- | --- | --- | --- | | `categoryKey` | `string` | yes | Category/label field name. Drives tooltip/legend/label text. | | `data` | `TDatum[]` | yes | Flat array of row objects. Each row is one slice/segment/spoke. | | `height` | `number` | yes | Container height in pixels. Width is always responsive. | | `valueKey` | `string` | yes | Numeric value field name. Drives slice/segment size. | | `accessibility` | `StandaloneAccessibilityOptions` | no | Accessible name, description, data table and keyboard navigation. No `announcements`: it switches ``'s interaction announcements, which this family does not make. | | `animation` | `StandaloneAnimationOption<"type">` | no | The entrance: on, off, `duration`, `easing` and the family's entrance `type`. One entrance and no series, so no `stagger`, `update`, `layers` or `exit` (ADR-082, LAB-AT17). | | `className` | `string` | no | Optional className applied to the outer container. | | `colors` | `string[]` | no | Categorical palette for this chart only: replaces the host palette (`--chart-1` … `--chart-10`) in the chart's colour assignment, and nothing else. It is a data encoding, not a theme: surfaces, text, grid and semantic roles keep coming from the CSS token contract, and a series, datum or annotation that sets its own colour keeps it. Any CSS colour string (a public token reference such as `var(--chart-3)`, hex, oklch). | | `contextMenu` | `FeatureOption, "copy" \| "export" \| "series">>` | no | The context menu. Opened on a slice, the host's builder receives a typed {@link CategoricalSlice} (datum, index, value, category, share) as `context.target.element`; on empty space the target is the chart, on a legend entry the entry. | | `dataLabels` | `boolean \| FunnelDataLabelOptions` | no | Data label configuration. Default: enabled with percentage. The label size and colour are the family's (its name and value roles), so the shared `fontSize` and `color` are not options here. | | `defaultSelectedItems` | `readonly ChartItemRef[]` | no | The initial selection of an uncontrolled chart. | | `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under ``. Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. | | `events` | `(Omit & ChartSelectionEvents>)` | no | The chart's events, and the selection events (T8): a stage is an item of the chart's one series (`seriesId` `'funnel'`), keyed by its `categoryKey` value unless `selection.itemKey` names another field. | | `gap` | `number` | no | Gap between segments in pixels. Default: 4. | | `legend` | `boolean \| LegendOptions` | no | Enable legend. | | `legendLink` | `ChartLegendLink` | no | Connects the chart's legend to `useChartLegend()`, for a legend the host renders itself. Give one link to one chart. | | `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. | | `minSegmentWidthFraction` | `number` | no | Minimum segment width as fraction of the widest segment. 0 = no minimum (default). | | `name` | `string` | no | The chart's name: its accessible name and `` (LAB-AT21). | | `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished. Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. | | `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. | | `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). | | `onItemActivate` | `((item: ChartSeriesItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). | | `onLegendChange` | `((change: ChartLegendChange) => void)` | no | Fired once for every legend change the chart applies: a hide, a show, an isolation or a show-all, from the built-in legend (click, key, double click, double tap), its menu, or `useChartLegend()`. The change names the entry and its target by identity and lists every hidden target after it. A refused action (the last visible target, `legend.interactive: false`) changes nothing and reports nothing. | | `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests. Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness. A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance). **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. | | `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartSeriesItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. | | `paint` | `DatumPaintResolver<DatumFill, TDatum>` | no | A stage's own fill, by a rule over its row (T1, the contract of BC-P1, ADR-092): the one stage below target in the negative role. Returns `{fill}` or `undefined` for the stage's palette colour; paint only. The stage IS its legend category, so its legend key, its tooltip swatch, its label's contrast surface and its export all show the painted fill; forced colours override it. The context's `seriesId` is `'funnel'` and its `seriesName` the chart's `name`. See {@link DatumPaintResolver}. | | `ref` | `Ref<ChartExportHandle>` | no | Imperative handle: exports and element access. A family built on this type has no data-range zoom, so its handle has no `setZoom`. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). | | `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. | | `selection` | `FeatureOption<ChartSelectionOptions>` | no | Item selection. `true` = single selection keyed by the default key. | | `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). | | `tooltip` | `StandaloneTooltipOption<never>` | no | Tooltip of the slice under the pointer: `enabled`, `renderer`, `valueFormatter` and `style` (ADR-082, LAB-AT17). | | `valueSemantics` | `ChartValueSemantics` | no | What the stage values mean (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The stage labels, the tooltip, the data table and the announcement write each value in it; a stage's share of the first stays a percentage. The label's own `formatter` or `format` (and `tooltip.valueFormatter`) still wins; without a declaration the chart presentation's number applies. CSV and Copy value keep the raw number. | | `width` | `number` | no | Optional fixed width in pixels. Default: fill container. | ## Types **FunnelChartProps** ```ts interface FunnelChartProps<TDatum extends ChartDatum = ChartDatum> extends Omit<CategoricalChartProps<TDatum>, 'events'>, ChartSelectionProps<TDatum, ChartSeriesItem<TDatum>> { events?: NonNullable<CategoricalChartProps<TDatum>['events']> & ChartSelectionEvents<TDatum, ChartSeriesItem<TDatum>>; name?: string; gap?: number; dataLabels?: FunnelDataLabelOptions | boolean; legend?: LegendOptions | boolean; legendLink?: ChartLegendLink; minSegmentWidthFraction?: number; valueSemantics?: ChartValueSemantics; paint?: DatumPaintResolver<DatumFill, TDatum>; } ``` Props for {@link FunnelChart}. Extends {@link CategoricalChartProps} to join the wrapper contract. Chart-specific fields (`gap`, `dataLabels`, `legend`, `minSegmentWidthFraction`) remain on this interface. Entrance animation: defaults to `stagger-segments` (sequential per-segment fade+slide). `fade` and `none` are also supported. Hover-transitions (100–150ms opacity) are retained as interaction feedback and fall below the WCAG 2.3.3 threshold for reduced-motion concerns; the global media query in `accessibility.css` suppresses them defensively under `prefers-reduced-motion: reduce`.