Scatter Plot

When to useCopy Anchor Link

• The user asks whether two measures are related: does spend drive signups, are pricier products rated higher, do longer calls close more deals.
• The user wants to spot outliers or clusters across many items measured two ways.

When not to useCopy Anchor Link

• One measure changes over time. Use a line Chart.
• You compare a few categories on one measure. Use a bar Chart.
• There are fewer than 5 items. Compare them in a Data Table or a sentence.
• You don't have the figures from a tool. Never invent or estimate points.

How the agent should use itCopy Anchor Link

• Copy data from the tool result unchanged, one row per item.
• Put the driver on x and the response on y: spend on x, signups on y.
• Name both axes in 1–4 words, with format, currency or unit so values read correctly. The titles are shown: the y title above its axis, the x title under the end of its axis, never rotated.
• Add size only for a third measure that matters (a bubble chart), like review count behind a rating. Never to decorate.
• Group by a category only when it explains the pattern. Up to 3 groups; a fourth and beyond fold into "Other".
• Set trend only when the relationship is the question and there are 5 or more points. The legend then names its strength from Pearson's r ("strong positive, r = 0.82"). Correlation is not cause: say "move together", not "causes".
• Highlight at most 5 points by name (outliers, the user's own item), and say why in summary.

DesignCopy Anchor Link

• Groups differ by colour and shape: vermilion, cool blue and cassis (the first three categorical colours, the only ones that stay distinct for every pair, in both themes) with circle, square and triangle; a fourth group and beyond fold into a neutral grey "Other" (diamond). A single set of points keeps the one-hue tone. A legend appears with two or more groups.
• Bubbles scale by area, not radius, so a point with twice the value looks twice as big. They're slightly translucent so overlaps stay visible, and every point has a ring in the card colour to keep neighbours apart.
• The trend line is a dashed straight line across the points' range. With fewer than 5 points, or when either measure doesn't vary, no line is drawn.
• Highlighted points carry their name beside them; every other point shows its name, group and values on hover. Small points have a larger invisible hover target.

AccessibilityCopy Anchor Link

The SVG is hidden from screen readers. A visually hidden table carries every point (name, group, both measures and size), captioned with the title, followed by the trend in words when there is one. Values are formatted with Intl, so they follow the user's locale.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

The Scatter Plot is display-only, so the tool can return immediately:

import { tool } from "ai"
import { scatterPlotTool } from "@/components/genui/scatter-plot.schema"

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

Render it through the Renderer under show_scatter, or directly:

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

Points render as they stream in.

SchemaCopy Anchor Link

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

SourceCopy Anchor Link