Skip to main content

Deflist

Typography styling for native <dl>, <dt>, <dd> elements, sitting alongside other classless typography element selectors (headings, body text, lists) shipped under src/foundation/typography/. With no orientation value the layout is a two-column grid that collapses to stacked on narrow viewports, with divider lines between rows and support for multiple <dd> per <dt>. This is the right element for key-value pairs, not tables - tables are for tabular data with multiple columns and headers.

Usage​

When to use

  • Key-value metadata displays (mission metadata, crew listings, product specs)
  • CMS field lists where the field formatter emits <dl>, <dt>, <dd> out of the box
  • Any pair-oriented content that is not tabular

When not to use

  • Tabular data with multiple columns - use <table>
  • A single pair - use inline text with <strong> or a heading
  • Navigation or lists of links - use <ul>

Do

  • Use real <dl>, <dt>, <dd> elements so assistive tech recognizes the relationship
  • Group consecutive <dd> siblings under one <dt> when a term has multiple values
  • Rely on the responsive grid - no extra classes needed

Don't

  • Don't wrap <dt>/<dd> pairs in extra <div>s - they break the implicit grouping
  • Don't use <dl> as a generic two-column layout primitive
  • Don't add striped row backgrounds - dividers are clearer for key-value lists

Choosing an orientation

The 3 layouts are separate states rather than one behaviour with a breakpoint:

  • No orientation value - two columns from 768px up, stacked below it. This is what a bare <dl> renders, and it suits body copy that has the full page width to work with.
  • horizontal - two columns at every width. Reach for it when the terms are short enough to hold their own column on a phone.
  • vertical - stacked at every width. Reach for it inside a narrow container, where a term column would leave the details too little room to read.

API​

Props​

PropTypeDefaultDescription
itemsarray-Array of {term, details} objects where term is the label string and details is an array of detail strings (each rendered as a sibling <dd>).
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.horizontalOrientationYesChildren flow along the horizontal axis.
.verticalOrientation-Children flow along the vertical axis.

Examples​

Single pair​

One term with one detail.

Multiple details per term​

One <dt> followed by multiple <dd> siblings (e.g. crew listing).

Long wrapping values​

Long value text that wraps across multiple lines in the detail column.

Orientations​

horizontal holds the two columns and vertical stacks the pair, both at every width.

Responsive layout​

The bare form, carrying no orientation value: two columns from 768px up, stacked below it. Resize the canvas to watch it collapse.

Dividers​

Horizontal rule between each row pair.

Accessibility​

  • WCAG 2.2 AA
  • Semantic <dl>, <dt>, <dd> - assistive tech recognizes the relationship automatically
  • No ARIA needed
  • Grid layout uses display: grid on the <dl> - screen readers still announce it as a description list (CSS display does not change semantic role).
  • Typography - heading, body text, and list classless counterparts
  • code - another classless typography component