ui/components/key-value

Key Value

Compound component for displaying labeled data. KeyValue wraps one or more KeyValue.Item rows in a semantic description list.

Preview

tsx

1 import { KeyValue } from "@/components/ui/key-value";2 3 export default function KeyValueDefault() {4   return (5     <KeyValue>6       <KeyValue.Item label="Provider" value="OpenAI" />7     </KeyValue>8   );9 }10

Installation

$pnpm exec dgadd add ui/key-value

[Installs to]src/components/ui/key-value[Item]ui/key-value

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { KeyValue } from "@/components/ui/key-value";2 3 export default function KeyValueDefault() {4   return (5     <KeyValue>6       <KeyValue.Item label="Provider" value="OpenAI" />7     </KeyValue>8   );9 }10

Examples

Variants

Preview

tsx

1 import { KeyValue } from "@/components/ui/key-value";2 3 export default function KeyValueVariants() {4   return (5     <div className="flex flex-col gap-4">6       <div className="text-xs text-muted-foreground uppercase font-bold">Horizontal (default)</div>7       <KeyValue>8         <KeyValue.Item label="Status" value="Default" variant="default" />9         <KeyValue.Item label="Response Time" value="120ms" variant="warning" />10         <KeyValue.Item label="API Version" value="v2.1" variant="info" />11         <KeyValue.Item label="Tests" value="Passing" variant="success" />12         <KeyValue.Item label="Errors" value="3 failures" variant="error" />13       </KeyValue>14       <div className="text-xs text-muted-foreground uppercase font-bold mt-4">Vertical Layout</div>15       <KeyValue layout="vertical">16         <KeyValue.Item label="Model" value="GPT-4o" variant="info" />17         <KeyValue.Item label="Tokens" value="1,234" />18         <KeyValue.Item label="Cost" value="$0.02" variant="success" />19       </KeyValue>20     </div>21   );22 }23

Description

Preview

tsx

1 import { KeyValue } from "@/components/ui/key-value";2 3 export default function KeyValueDescription() {4   return (5     <KeyValue>6       <KeyValue.Item7         label="Provider"8         value="OpenRouter"9         description="Routes each request to the cheapest healthy upstream for the selected model."10       />11       <KeyValue.Item label="Model" value="claude-sonnet-4" variant="info" />12     </KeyValue>13   );14 }15

Bordered

Preview

tsx

1 import { Badge } from "@/components/ui/badge";2 import { KeyValue } from "@/components/ui/key-value";3 4 export default function KeyValueBordered() {5   return (6     <KeyValue bordered>7       <KeyValue.Item label="API Key Status" value={<Badge variant="info">[ STORED ]</Badge>} />8       <KeyValue.Item label="Provider" value="OpenRouter" />9     </KeyValue>10   );11 }12

List

Preview

tsx

1 import { KeyValue } from "@/components/ui/key-value";2 3 export default function KeyValueList() {4   return (5     <KeyValue bordered>6       <KeyValue.Item label="Commit" value="a1b2c3d" variant="info" />7       <KeyValue.Item label="Author" value="Ada Lovelace" />8       <KeyValue.Item label="Date" value="2026-02-10 14:30" />9       <KeyValue.Item label="Branch" value="feature/add-toasts" variant="info" />10       <KeyValue.Item label="Files Changed" value="7" variant="success" />11     </KeyValue>12   );13 }14

API Reference

KeyValue

Name	Type	Default	Description
layout	"horizontal" \| "vertical"	"horizontal"	Horizontal places label and value side-by-side; vertical stacks them. Propagated to KeyValue.Item via context.
bordered	boolean	false	Adds top separators between rows and switches items to compact xs sizing. Propagated to KeyValue.Item via context.
childrenrequired	ReactNode	—	KeyValue.Item rows rendered inside a semantic <dl>.

KeyValue.Item

Name	Type	Default	Description
labelrequired	ReactNode	—	Label content rendered in a <dt>.
valuerequired	ReactNode	—	Value content rendered in a <dd>.
description	ReactNode	—	Optional qualifying copy for the pair, rendered as a second <dd> that spans the full row. Omit it and no element is rendered.
variant	"default" \| "warning" \| "info" \| "success" \| "error"	"default"	Color token applied to the value. Info renders monospace in the info color; the rest are bold semantic colors.
layout	"horizontal" \| "vertical"	inherited from KeyValue	Per-row override of the parent layout.
bordered	boolean	inherited from KeyValue	Per-row override for the inter-row top separator and compact sizing.
className	string	—	Class applied to the <dt> in addition to the variant classes. Other forwarded props land on the <dt> too.
valueClassName	string	—	Class applied to the value <dd> in addition to the variant classes.
descriptionClassName	string	—	Class applied to the description <dd> in addition to the variant classes.

Accessibility

Notes

When to use KeyValue vs Label

Use KeyValue for structured multi-row data display (metadata panels, commit info). Use Label for form field labeling.

Compound Usage

Always wrap KeyValue.Item inside KeyValue — this produces a proper <dl> list. For a single pair: <KeyValue><KeyValue.Item label='...' value='...' /></KeyValue>.

Color Variants

5 semantic color variants (default, warning, info, success, error) style the value text. The info variant renders monospace in the info color instead of bold.

Bordered Rows

Set bordered on KeyValue or KeyValue.Item to add top separators between rows, vertical padding, and compact text-xs sizing — ideal for stacked list layouts.

Layout Options

Horizontal layout (default) places label and value side-by-side. Vertical layout stacks them with a small gap. Both label and value accept ReactNode.

Descriptions

Pass description to qualify a pair with a line of muted copy. It renders as a second <dd> for the same <dt>, spanning the full row in horizontal layout — so callers never have to restate the grid's column count.

Class Slots

KeyValue.Item renders up to three elements: className (and every other forwarded prop) lands on the <dt>, valueClassName on the value <dd>, descriptionClassName on the description <dd>. All preserve the <dl>/<dt>/<dd> structure.

Source

Install via CLI: pnpm exec dgadd add ui/key-value.

Highlighted source loads after this disclosure opens. Browse the source repository.

Key Value

Installation

Usage

Examples

Variants

Description

Bordered

List

API Reference

KeyValue

KeyValue.Item

Accessibility

Notes

When to use KeyValue vs Label

Compound Usage

Color Variants

Bordered Rows

Layout Options

Descriptions

Class Slots

Source

View component source (8 files)