Data display

Key-value list

<forma-key-value-list>

Description-list presentation of labelled values that stacks label above value on narrow screens.

Authoring tag
<forma-key-value-list>
Category
Data display
Behavior owner
Native HTML
Canonical source
patterns/key-value-list.html

Purpose

A key-value list shows the facts about one object as label/value pairs. It is a native dl whose dt/dd pairs are grouped in div rows; Forma lays each row out as a two-column grid with a ruled separator and stacks the label above the value at phone width. The list is static content: the application supplies the labels, the values and how missing values are worded.

Use when

  • A record, account or object has a handful of named properties to read, such as plan, owner, renewal date or region.
  • Labels are nouns and each has exactly one value (which may contain a link, a date or a Status lozenge).
  • The same facts must read well on a phone without a table.

Avoid when

  • Many records share the same fields: use Data grid or Dense ledger.
  • Values are compared between two versions or options: use Comparison pairs or Diff viewer.
  • The labels describe relationships between entities rather than properties: use Relationship index.
  • Short marketing claims with supporting detail are shown on a public page: use Facts.
  • The values are editable: use form controls such as Text field with real labels.

Behavior to know

  • Label column is minmax(7rem, 0.35fr); the value column takes the remaining width and can shrink to zero, so long values wrap instead of overflowing.
  • Each row has a subtle bottom rule, so pairs stay visually grouped when values wrap onto several lines.
  • At 30rem and below each row becomes a single column with the label directly above its value.

Basic example

The smallest correct markup: the canonical pattern from patterns/key-value-list.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal key-value list

Rendered from the canonical pattern file.

Account
Northwind Logistics
Plan
Team, billed annually
Renewal
HTML · Minimal key-value list Raw HTML for HTML · Minimal key-value list
<forma-key-value-list class="forma-component-tag">
<dl class="forma-key-value-list">
  <div><dt>Account</dt><dd>Northwind Logistics</dd></div>
  <div><dt>Plan</dt><dd>Team, billed annually</dd></div>
  <div><dt>Renewal</dt><dd><time datetime="2027-03-01">1 March 2027</time></dd></div>
</dl>
</forma-key-value-list>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Record details with status and links

A deployment's properties. Values mix plain text, an Identifier & critical value, a link, a machine-readable time and a Status lozenge; the list itself stays a plain description list.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Deployment details

Release
rel-2026.09.29-3f8c21
Environment
Production, EU West
Status
Healthy
Started
HTML · Record details with status and links Raw HTML for HTML · Record details with status and links
<forma-key-value-list class="forma-component-tag">
  <section aria-labelledby="key-value-list-record-details-title">
    <h3 id="key-value-list-record-details-title">Deployment details</h3>
    <dl class="forma-key-value-list">
      <div><dt>Release</dt><dd><span class="forma-identifier">rel-2026.09.29-3f8c21</span></dd></div>
      <div><dt>Environment</dt><dd>Production, EU West</dd></div>
      <div><dt>Status</dt><dd><span class="forma-status-lozenge" data-state="ok">Healthy</span></dd></div>
      <div><dt>Started</dt><dd><time datetime="2026-09-29T07:42:00Z">29 Sep 2026, 07:42 UTC</time></dd></div>
      <div><dt>Owner</dt><dd><a href="#key-value-list-record-details-owner">Platform team</a></dd></div>
    </dl>
  </section>
</forma-key-value-list>

Click or tap the code once to select all of it, then copy.

Scenario

Long labels and missing values

German labels (marked with lang="de") that are longer than the 7rem minimum label column wrap within it, and values that are not set are written out rather than left blank so an empty dd is never mistaken for a loading value.

Verantwortliche Abteilung für Rechnungsprüfung
Finanzbuchhaltung Mitteleuropa
Kostenstelle
Nicht festgelegt
Umsatzsteuer-Identifikationsnummer
DE 812 345 678
Letzte Prüfung
Unbekannt: Prüfprotokoll nicht verfügbar
HTML · Long labels and missing values Raw HTML for HTML · Long labels and missing values
<forma-key-value-list class="forma-component-tag">
  <dl class="forma-key-value-list" lang="de">
    <div><dt>Verantwortliche Abteilung für Rechnungsprüfung</dt><dd>Finanzbuchhaltung Mitteleuropa</dd></div>
    <div><dt>Kostenstelle</dt><dd>Nicht festgelegt</dd></div>
    <div><dt>Umsatzsteuer-Identifikationsnummer</dt><dd><span class="forma-identifier">DE 812 345 678</span></dd></div>
    <div><dt>Letzte Prüfung</dt><dd>Unbekannt: Prüfprotokoll nicht verfügbar</dd></div>
  </dl>
</forma-key-value-list>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile account summary

An account summary at phone width. Each row stacks its label above its value so neither is squeezed into a narrow column.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 30rem (480px) and below each row switches to grid-template-columns: 1fr with a 0.25rem gap: the label sits directly above its value.
  • The row rule stays, so pairs remain grouped even when a value wraps across several lines.
  • Long unbroken values should use Identifier & critical value (which allows breaking anywhere) so they wrap at 320px instead of overflowing.
  • Links inside values are ordinary inline links; give them enough text to be comfortable tap targets or place them on their own line.
  • Orientation changes only switch between the stacked and two-column rows at the 30rem breakpoint.
HTML · Mobile account summary Raw HTML for HTML · Mobile account summary
<forma-key-value-list class="forma-component-tag">
  <dl class="forma-key-value-list">
    <div><dt>Account</dt><dd>Northwind Logistics International</dd></div>
    <div><dt>Plan</dt><dd>Business, billed monthly</dd></div>
    <div><dt>Seats</dt><dd>48 of 50 in use</dd></div>
    <div><dt>Billing contact</dt><dd><a href="#key-value-list-mobile-account-summary-contact">accounts-payable@northwind.example</a></dd></div>
  </dl>
</forma-key-value-list>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
datetimetimeISO date or date-time—Machine-readable form of a date value; the visible text stays human-formatted.
aria-labelledbywrapping sectionid of a heading—Names the section that contains the list when the list has a visible heading.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-key-value-listBlock class—The native dl. Each direct div child is a label/value row laid out as a two-column grid with a subtle bottom rule.
Keyboard interaction
KeysResult
TabOnly interactive content inside values (links, buttons) is focusable; the list itself is not.

Form behavior

Not a form control. Display values only; editable fields need real form controls.

States

Key-value list states
StateHow it is expressedPresentation
Two-column rowsviewport > 30remLabel column minmax(7rem, 0.35fr) beside a flexible value column.
Stacked rowsviewport ≤ 30remLabel above value in a single column.
Missing or unknown valueapplication text in the ddWritten as words (Not set, Unknown); Forma adds no special styling.

Accessibility

Forma provides

  • Uses the native description list, so assistive technology exposes each term with its description.
  • Keeps DOM order and reading order identical at every width; only the grid columns change.
  • Allows the value column to shrink (minmax(0, 1fr)), so long values wrap instead of creating horizontal scrolling.

Your application supplies

  • Wrap each dt/dd pair in a div directly inside the dl; that div is the styled row.
  • Give the list a heading or section name when there are several lists on a page.
  • Write missing, unknown and not-applicable values as text.
  • Do not put state only in color; use Status lozenge text inside the value.

Responsive behavior

  • Two columns above 30rem: minmax(7rem, 0.35fr) minmax(0, 1fr) with a 1rem gap.
  • At 30rem and below each row stacks into one column with a 0.25rem gap.
  • Long labels wrap within the label column; long values wrap within the value column.
  • The value dd keeps the browser's default inline-start margin, so values are indented by the user agent's default at every width.

Motion

  • No animation: the layout switch at 30rem is instant and nothing transitions.

Usage guidance

Do

Avoid

  • Using a key-value list for a table of many records.
  • Leaving a dd empty to mean unknown or none.
  • Placing several unrelated values in one dd; split them into rows.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.