Distribution Chart

When to useCopy Anchor Link

• The user asks how values are spread: what's typical, how wide the range is, whether there are outliers or a long tail (how long deliveries usually take, how salaries vary by level).
• The user wants to see where one value falls among many (my score against the class, our price against competitors).

When not to useCopy Anchor Link

• You only have averages or totals, not the individual values. Say them in a sentence or use a Chart.
• One measure changes over time. Use a line Chart.
• The question is whether two measures move together. Use a Scatter Plot.
• There are fewer than 5 values. List them.

How the agent should use itCopy Anchor Link

• Pass one row per individual value from the tool result. Never bin, average or round them yourself: the component computes the bins, quartiles and outliers.
• Pick the form for the job:
  • histogram for the shape of one set of 30 or more values (a peak, a long tail, two humps).
  • box to compare spread across 2–6 groups (salary by level, response time by tier).
  • dots for up to about 80 values, or when each item matters: every value is a dot, with its name on hover.
• Name the measure in 1–4 words, with format, currency or unit.
• Add a marker for the user's own value, a target or a limit, at most 3.
• In summary, say what's typical and how wide the spread is in plain words. Outliers are unusual values, not errors.

DesignCopy Anchor Link

• Facts first. For one set of values, a row under the title gives the median, the middle half (first to third quartile), the range and the count. With groups, each row's figures are on hover and in the table.
• Histogram. Bins have a round width (1, 2, 2.5 or 5 × 10ⁿ) and start on a round edge, so ranges read as "30–35 min". Without bins, the count follows Sturges' rule (about log₂ n + 1, between 5 and 30). Hovering a bar shows its range, count and share.
• Box plot. One row per group: the box spans the middle half, the dark line is the median, whiskers reach the furthest values within 1.5 × the box's width, and points beyond them are drawn as hollow outliers, each with its name on hover.
• Dots. Values fall into columns one dot wide and stack outwards from the row's centre line; dots shrink when a stack would outgrow its row.
• Markers are dashed lines across the plot with their label above. The value axis always includes them.
• One neutral colour throughout: groups are told apart by their row label, not by colour.

AccessibilityCopy Anchor Link

The SVG is hidden from screen readers. A visually hidden summary table (per group when grouped) gives the count, median, middle half, range and outliers; a histogram adds the count per range, and markers are listed after. Values are formatted with Intl, so they follow the user's locale.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

The Distribution Chart is display-only, so the tool can return immediately:

import { tool } from "ai"
import { distributionChartTool } from "@/components/genui/distribution-chart.schema"

const tools = {
  [distributionChartTool.name]: tool({
    description: distributionChartTool.description,
    inputSchema: distributionChartTool.inputSchema,
    execute: async () => ({ shown: true }),
  }),
}

Render it through the Renderer under show_distribution, or directly:

<DistributionChart {...part.input} status={part.state === "input-streaming" ? "streaming" : "ready"} />

Values render as they stream in.

SchemaCopy Anchor Link

Host props: status (streaming or ready) and className.

SourceCopy Anchor Link