Quantity Scaler

When to useCopy Anchor Link

• Quantities depend on a headcount the user may change: a recipe, party supplies, catering, packing for a group.
• The user asked how much to buy or bring for a number of people.

When not to useCopy Anchor Link

• The count is fixed and final. Give the list in text.
• The quantities depend on more than one number, like a budget or a duration. Use a Calculator.
• You don't know the per-person amounts. Find a source first; the quantities are data, not guesses.

How the agent should use itCopy Anchor Link

• Set base to the count the quantities are written for, and value to what the user asked for. "Lamb roast for 5" from a recipe for 4 is base: 4, value: 5.
• Name what the count counts with unitLabel: { singular: "guest", plural: "guests" }. The card shows "Number of guests" over the big number and "Guests" under it.
• Choose a scale per item. linear (the default) grows with the count. fixed never changes ("1 oven tray", "1 bunch of rosemary"). step rounds up to whole units (eggs, packs).
• Give each item its natural unit. Leave unit empty for a count.
• Keep note to one line (120 characters), and only when it changes what to buy.
• Lifecycle: quantities from a recipe are a snapshot, so none of expiresAt or fetchedAt is needed. When the agent sends a revised list (another recipe, more items), mark the old call superseded by the new one.

RoundingCopy Anchor Link

Amounts are rounded so they read like a shopping list, never down to zero:

Set round (decimal places) on an item to override this. With round, the unit is kept as given, counts still round up and everything else rounds to the nearest value.

InteractionCopy Anchor Link

• The count changes with the round − and + buttons, by typing into the big number, or with the arrow keys (Page Up/Down by 5, Home/End to the limits). It stays within min and max (default 1–50).

• The number is a spinbutton labelled "Number of people"; button presses are announced ("6 people"), and each quantity has its exact value for screen readers while the digits roll.

• "Copy shopping list" copies a plain list:

  Copy Text

  For 5 people
  • Bone-in leg of lamb — 2.0 kg
  • Potatoes — 1.5 kg
  • Carrots — 8

• The scaler never locks. While streaming, items appear one by one and the count can't be changed until the call finishes.

InstallationCopy Anchor Link

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

This adds the component, its schema and quantity-scaler-utils.ts (scaling, rounding and the copied text).

UsageCopy Anchor Link

import { tool } from "ai"
import { quantityScalerTool } from "@/components/genui/quantity-scaler.schema"

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

import { QuantityScaler } from "@/components/genui/quantity-scaler"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-scale_quantities") return null

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

The scaler is useful on its own, so the tool can also have an execute that returns immediately; then send onResult calls to the agent as messages instead. It sends set about 0.7 seconds after the user settles on a count, with the amounts as shown, so the agent knows the final headcount:

{
  action: "set",
  value: 6,
  items: [
    { id: "lamb", quantity: 2.4, unit: "kg" },
    { id: "potatoes", quantity: 1.8, unit: "kg" },
    { id: "carrots", quantity: 9, unit: "" },
  ],
}

// After "Copy shopping list"
{ action: "copy" }

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

When a conversation is reloaded, pass the stored result back as result. A set result restores the count the user chose. The scaler stays usable, but it never calls onResult again, so nothing is sent twice:

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

SchemaCopy Anchor Link

Item

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

SourceCopy Anchor Link