FLITTERChart
API Reference

Funnel Chart API

Sequential conversion stages with AG and Toast styles, editable geometry and interactive tooltips.

Data Format

Stages remain in input order. Values are non-negative volumes; invalid or negative values become zero. Width is proportional to the largest input value. Empty and all-zero data render without marks. Percentages use the original data even when a stage is hidden.

type FunnelChartData = {
  stages: { label: string; value: number }[];
};
AG Style Config

Funnel

PropertyTypeDefaultDescription
funnel.gapnumber3Vertical gap between stages in pixels.
funnel.widthRationumber0.64Fraction of plot width reserved for the funnel; the remaining width holds labels.
legend.visiblebooleanfalseShow interactive stage keys. Hiding a stage preserves the original conversion denominators and color indices.
dataLabel.visiblebooleantrueShow labels beside each stage.
dataLabel.colorstringStyle legend colorLabel text color. Set this for a custom background.
dataLabel.formatter(stage: FunnelStage) => stringLabel, value and percentageFormats stage labels. percentage is relative to the original first stage; conversion is relative to the original previous stage.

AG Hover

PropertyTypeDefaultDescription
funnel.dimOpacitynumber0.35Opacity of other stages while one is hovered. The tooltip follows the pointer.
Toast Style Config

Funnel

PropertyTypeDefaultDescription
funnel.gapnumber3Vertical gap between stages in pixels.
funnel.widthRationumber0.64Fraction of plot width reserved for the funnel; the remaining width holds labels.
legend.visiblebooleanfalseShow interactive stage keys. Hiding a stage preserves the original conversion denominators and color indices.
dataLabel.visiblebooleantrueShow labels beside each stage.
dataLabel.colorstringStyle legend colorLabel text color. Set this for a custom background.
dataLabel.formatter(stage: FunnelStage) => stringLabel, value and percentageFormats stage labels. percentage is relative to the original first stage; conversion is relative to the original previous stage.

Toast Hover

PropertyTypeDefaultDescription
funnel.hoverBorderColorstring"white"Outline color of the hovered stage.
funnel.hoverBorderWidthnumber4Outline thickness in pixels. The tooltip is anchored to the hovered stage.
animation.enabledbooleantrueEnable the entrance reveal. Disable for static exports.

Custom Parts

Override any visual element by providing a custom builder function: (args, context) => Widget

PartArgsDescription
layout{ title, legends, plot }Title, stage keys and plot layout.
plot{ stages: { stage, widget }[], tooltipArea }Position stage widgets using normalized geometry.
stageFunnelStage & { isHovered, dataLabel }Stage shape. Headless owns hover handling.
dataLabelFunnelStageContent beside each stage.
tooltipFunnelStageHovered stage details, value and conversion rates.
tooltipArea{ stage, tooltip }Style-specific tooltip placement.
legend{ name, index, isVisible }Stage key. Headless owns the visibility toggle.
titleundefinedChart heading.

Context: FunnelChartContext

Available in every custom builder via the second argument.

NameTypeKindDescription
stagesFunnelStage[]propertyVisible stages with original indices, value, percentage, conversion and normalized top/height/topWidth/bottomWidth.
hoveredStageFunnelStage | nullpropertyCurrent hovered stage.
toggleStage(index)(index: number) => voidmethodToggle a stage by its original input index.
unhoverAllStages()() => voidmethodClear hover state.

Custom Part Example

import FunnelChart from "@/components/flitter/charts/funnel-chart";

const widget = FunnelChart({
  data: { stages: [
    { label: "Visits", value: 12000 },
    { label: "Trial", value: 4800 },
    { label: "Paid", value: 1200 },
  ] },
  config: { title: { text: "Product Conversion" }, legend: { visible: true } },
});