Comparison Matrix

When to useCopy Anchor Link

• The user wants to compare 2–5 options across the same criteria: plans, products, vendors, candidates, approaches.
• Seeing where the options differ is the point, and the user may pick one.

When not to useCopy Anchor Link

• There's one option. Use an Entity Card or a Summary Card.
• There are more than 5 options, or many records with the same fields. Use a Data Table.
• The options differ on one number. Say it in a sentence, or use a Chart.
• The agent can't read the real values. Fetch them first; never fill gaps from memory.

How the agent should use itCopy Anchor Link

• Every value comes from a tool result. Use null for anything unknown. It's shown as "—" and read as "not known", never guessed.
• Use the same criteria for every option, grouped (Pricing, Features, Support) and ordered by what the user asked about.
• Set better only where one direction clearly wins: price lower, battery higher. Leave it off for neutral facts like screen size.
• Add weight only when the user's priorities are known, like "for video editing". The score is computed from the values; the agent doesn't state its own.
• A recommendation must follow from the values shown, and its reason must cite them.
• Set selectable only when the choice changes what the agent does next, like switching plans. Act only on a select result.
• Lifecycle: prices and plan terms change, so set fetchedAt (and staleAfterMs, e.g. a day) on the call when the values come from a live catalog. When a selectable comparison is built on a quote that only holds for a while, set expiresAt too. Use supersede when the agent re-runs the comparison with different options or criteria.

InteractionCopy Anchor Link

While streaming, the column headers arrive first and each row appears once its first value arrives. Best marks wait for the whole row, and same rows fold only once the call is complete, so nothing jumps.

Weighted scoreCopy Anchor Link

Only booleans and rows with better and a weight above 0 count:

score(item) = round(100 × Σ weight × n(item) / Σ weight)

number, currency, rating:  n = (v − min) / (max − min)   when better is "higher"
                           n = (max − v) / (max − min)   when better is "lower"
                           (min and max over the known values in the row; all equal → 1)
boolean:                   n = 1 for Yes, 0 for No
unknown (null):            n = 0, so missing data can't win

The helpers in comparison-matrix-utils.ts (weightedScores, bestItemIds, partitionRows, formatValue) are pure, so the server can reuse them, for example to check that a recommendation matches the top score.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { comparisonMatrixTool } from "@/components/genui/comparison-matrix.schema"

const tools = {
  // Selectable: no execute(), the call is completed by the user's choice.
  // Display-only: add an execute that returns immediately.
  [comparisonMatrixTool.name]: tool({
    description: comparisonMatrixTool.description,
    inputSchema: comparisonMatrixTool.inputSchema,
  }),
}

<ComparisonMatrix
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) =>
    addToolResult({ tool: "compare_options", toolCallId: part.toolCallId, output: result })
  }
/>

With selectable, the agent receives one of:

{ action: "select", itemId: "growth" }
{ action: "dismiss" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "compare_options", props: { toolCallId, ...args } }, { message }). For a selectable comparison, interrupt() until the user's result arrives. Render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The matrix renders read-only, with the chosen column highlighted and its radio checked, and the footer shows "Chose Growth" (or "Dismissed. Nothing was chosen."). It never calls onResult again.

<ComparisonMatrix
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Item

Criterion

Host props: status (streaming, ready, submitting, selected, dismissed), onResult, result and className.

SourceCopy Anchor Link