Funnel

When to useCopy Anchor Link

• The user asks how a multi-step flow converts or where people drop off: checkout, signup, onboarding, a trial-to-paid path.
• You have per-step counts from analytics, optionally for a previous period or by segment (device, channel, plan).

When not to useCopy Anchor Link

• The steps aren't sequential, or people can enter at any step. Use a Chart or a Data Table.
• The question is about one number over time. Use a KPI Card or a chart.
• You don't have real counts. Don't invent or estimate them.

How the agent should use itCopy Anchor Link

• Every count must come from the tool result, in funnel order. Percentages, drop-offs, the biggest drop and the overall conversion are computed by the component, so the agent never does the arithmetic.
• Set previous per step only when you have the same steps for the comparison period, and name that period in period.compareLabel.
• Give segments the same steps in the same order, at most 4. A segment whose counts doesn't have one value per step is left out, with a note saying why.
• Add value.perConversion only when you know the real value of one conversion (e.g. average order value). The card then sizes the biggest drop in one line.
• Keep insight to one sentence that names the step and a number from the data.
• Drill-down and export are the user's requests, not actions you've taken: fetch the step's detail when asked.
• Lifecycle: this is analytics data, so set fetchedAt (and staleAfterMs, e.g. an hour for a live dashboard or a day for weekly reports) on the call. When the user re-queries the same funnel (a new period, another segment split), mark the old call superseded by the new one. No expiresAt.

What it showsCopy Anchor Link

SegmentsCopy Anchor Link

With segments, the header gets a segmented control: All, one option per segment, and Compare. A segment view shows the same funnel with that segment's counts and its own overall conversion (no previous period, since segments don't carry one). Compare leads with each segment's overall conversion in one row, then small grouped bars per step, one per segment, each as a share of that segment's own first step, so conversion rates line up even when the segments differ in size. Segments are told apart by their name next to each bar and the legend order, not only by fill.

The view is local to the card. When the user drills into a step while a segment is selected, its id is included in the result.

InteractionCopy Anchor Link

The card never locks: it's a view of the data with ways into it.

• Drill into a step: the footer's "Drill into step" menu lists every step.
• Export CSV: builds the CSV in the browser (one row per step: count, % of first step, step conversion, previous, and each segment's count), downloads it, and tells the agent. Fields are escaped, and text that a spreadsheet could run as a formula is prefixed with '.

AccessibilityCopy Anchor Link

The bars are hidden from screen readers. Each view is a figure with a one-sentence summary (aria-label) and a visually hidden table of steps × count, % of first step, step conversion and previous (or per-segment counts in Compare). Compact counts carry the full number in a visually hidden span, and the rolling overall conversion keeps its real value in one too. Changes show a sign, an arrow and text, and "Biggest drop" is text with an icon, so color is never the only cue. The segment control is a native radio group (arrow keys move between options) with a visible focus ring, and view switches and exports are announced in a polite live region. Bar animations are skipped with reduced motion.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/funnel.json

UsageCopy Anchor Link

import { tool } from "ai"
import { funnelTool } from "@/components/genui/funnel.schema"

const tools = {
  [funnelTool.name]: tool({
    description: funnelTool.description,
    inputSchema: funnelTool.inputSchema,
  }),
}

Without actions the funnel is display-only, so give the tool an execute that returns immediately. With them, the agent (or your host) receives one result per press:

{ action: "drill-down", stepId: "checkout", segmentId: "mobile" } // segmentId only in a segment view
{ action: "export" } // the CSV is already downloaded in the browser

<Funnel
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : "ready"}
  onResult={(r) => sendToAgent(part.toolCallId, r)}
/>

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_funnel", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

There's no finished state to restore. Render the stored tool input again; the card stays live and opens on All.

SchemaCopy Anchor Link

Host props: status (streaming, ready), onResult and className.

SourceCopy Anchor Link