key_value

What a thing is. key_value answers "tell me about order 1042" with the order's own facts, one label and one value per row.

It exists because the alternative is a paragraph. A shipping date buried in prose has to be read; the same date on its own row is found.

Order 1042

Placed21 Aug

ItemsAero Glide 2, size 43

StatusShipped

Re-rendered in the browser from the SDK’s own scales. Not a screenshot.

Rendered natively by the Flutter SDK and the Web SDK, both since 0.1.0.

When not to use it

Do not use it for several things that share the same fields, which is table: three orders with a date and a status each are rows in a table, not three detail sheets.

Do not use it for a delivery's progress, which is order_tracker, and do not use it for money that adds up, which is receipt. A receipt has a total, and a total is arithmetic the reader should not have to do.

Props

Every block also carries type and a required fallback_text of 1 to 300 characters.

Prop	Type	Required	Constraints
`title`	string	No	Up to 120 characters.
`rows`	array	Yes	1 to 12 entries.
`rows[].label`	string	Yes	1 to 60 characters.
`rows[].value`	string	Yes	1 to 200 characters.
`rows[].emphasis`	boolean	No	Lifts one row out of the ramp.
`cta`	object	No	None
`cta.label`	string	Yes	1 to 60 characters.
`cta.action`	action	Yes	`{ kind: "reply", text }` or `{ kind: "open_url", url }`. See Actions.

On the wire

{
  "id": "blk_21",
  "type": "key_value",
  "fallback_text": "Order 1042, placed 21 August, one pair, shipped.",
  "props": {
    "title": "Order #1042",
    "rows": [
      { "label": "Placed", "value": "21 Aug" },
      { "label": "Items", "value": "Aero Glide 2, size 43" },
      { "label": "Status", "value": "Shipped", "emphasis": true }
    ],
    "cta": { "label": "Track it", "action": { "kind": "reply", "text": "Track order 1042" } }
  }
}

Interaction

Only the optional cta. The rows themselves are a readout and are not tappable.

States

State	What the SDK draws
Loading	Label and value bars at the real row height.
Long value	The value wraps and stays right-aligned; the label never truncates.
Empty	An empty `rows` array renders `fallback_text` inside the plate.

Accessibility

Each row is announced as its label followed by its value, so the pairing survives being read aloud in one pass. emphasis changes weight, never colour alone.

Use emphasis once at most. A sheet where every row is emphasised has no answer in it, only twelve equal facts.