FunnelChart
Ordered conversion stages drawn as a funnel or flush bars, with value and share labels.
stable
Quick Preview
Application funnel
Monthly buyer conversion
- 1,200 · 100%
- 420 · 35%
- 180 · 15%
- 96 · 8%
- Viewed
- Qualified
- Applied
- Approved
Usage
import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
import { FunnelChart } from "@giddaa-housing/ui/funnel-chart";
<ChartCard>
<ChartHeader><ChartTitle>Application pipeline</ChartTitle></ChartHeader>
<FunnelChart
data={[
{ stage: "Viewed", buyers: 1200 },
{ stage: "Applied", buyers: 540 },
{ stage: "Approved", buyers: 210 },
]}
categoryKey="stage"
valueKey="buyers"
ariaLabel="Buyers reaching each stage"
/>
</ChartCard>Pass stages in funnel order, widest first. Stages are shaded with the brand color
at decreasing opacity, because a funnel encodes what remains, not separate
categories. A column of value · share labels sits beside the plot, and the stage
legend sits to the right (legend="bottom" or false to move or hide it).
Compose title and description with ChartCard.
Examples
Default
Application funnel
Monthly buyer conversion
- 1,200 · 100%
- 420 · 35%
- 180 · 15%
- 96 · 8%
- Viewed
- Qualified
- Applied
- Approved
Bars
variant="bars" draws flush, left-aligned bars instead of connected trapezoids,
which reads better when stage values are close.
<FunnelChart data={stages} categoryKey="stage" valueKey="buyers" variant="bars" ariaLabel="Buyers per stage" />Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | Stages in funnel order, widest first. |
categoryKey | string or number field of T | required | Field naming each stage. |
valueKey | numeric field of T | required | Nonnegative count reaching each stage. |
ariaLabel | string | required | Accessible chart name. |
colorKey | string field of T | brand ramp | Field holding a stage's CSS color. |
variant | "funnel" | "bars" | "funnel" | Connected trapezoids or flush bars. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Plot and type scale (FUNNEL_CHART_LAYOUT). |
legend | "right" | "bottom" | false | "right" | Stage legend placement. A right legend wraps under the plot when it runs out of room; stacked, the plot is centered. |
legendMinWidth | number | content width | Narrowest a right legend gets, in px, before it wraps under the plot. |
valueLabels | boolean | true | Column of value · share labels beside the plot. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | grouped number | Stage values. |
formatShare | (share: number) => string | whole percent | Value-label and tooltip shares of the first stage; share is 0–1. |
formatCategory | (value: string | number) => string | String | Stage names. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid stages exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
createFunnelChartDefinition(options) | function | - | Same options without the HTML legend and labels; returns an extensible TanStack definition. |
funnelColor(index, count), FUNNEL_CHART_OPACITIES | helpers | - | The brand ramp, for custom legends. |
Accessibility
- Provide a meaningful
ariaLabel; focus the chart and use arrow keys to move between stages. - Keep
valueLabelson: the share of the first stage is stated in text, not just width. - Order stages logically; a funnel implies each stage is a subset of the one before.