dl-item

Groups a dt/dd pair within a description list for styling purposes.

Description

The <dl-item> custom element is a structural wrapper that groups a <dt>/<dd> pair within a <dl> (description list). It exists purely for styling purposes, enabling grid and flex layouts that treat each term-description pair as a unit.

This element has no semantic meaning itself—it simply provides a styling hook that the native HTML structure lacks. The <dl> element allows <div> wrappers for this purpose, and custom elements work the same way.

When to Use

Inside <dl class="key-value"> description lists
When you need horizontal (grid) or stacked (flex) layouts for term-description pairs
With @scope CSS rules that target the key-value pattern

When Not to Use

Outside of a <dl> element
For basic description lists that don't need row-based styling
When the default indented <dd> styling is sufficient

Basic Usage

Wrap each <dt>/<dd> pair in a <dl-item> element within a description list.

Full Name: Alexandra Chen
Email: alexandra.chen@example.com
Status: Active

<dl class="key-value"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Email</dt> <dd>alexandra.chen@example.com</dd> </dl-item> <dl-item> <dt>Status</dt> <dd>Active</dd> </dl-item> </dl>

Multiple Values

A single <dl-item> can contain one <dt> with multiple <dd> elements for terms that have several values.

Phone Numbers: +1 (555) 123-4567; +1 (555) 987-6543

<dl class="key-value"> <dl-item> <dt>Phone Numbers</dt> <dd>+1 (555) 123-4567</dd> <dd>+1 (555) 987-6543</dd> </dl-item> </dl>

CSS Implementation

The base element is simply a block container:

dl-item { display: block; }

The actual layout styling is applied via @scope rules that target the .key-value pattern class.

Horizontal Layout

For side-by-side label-value display:

@scope (.key-value) { dl-item { display: grid; grid-template-columns: 140px 1fr; gap: var(--size-m); align-items: baseline; padding-block: var(--size-s); border-bottom: 1px solid var(--color-border); } dl-item:last-child { border-bottom: none; } }

Stacked Layout

For vertical stacking with label above value:

@scope (.key-value[data-layout="stacked"]) { dl-item { display: flex; flex-direction: column; gap: var(--size-2xs); } }

Why a Custom Element?

Using <dl-item> instead of <div> provides several benefits:

Semantic clarity: The element name describes its purpose—grouping a description list item
Targeted styling: CSS selectors like dl-item are more specific than div
Pattern recognition: Easy to identify key-value patterns in the HTML
No JavaScript required: The element works as a pure styling hook

Note: HTML5 explicitly allows wrapping <dt>/<dd> pairs in <div> elements, and custom elements inherit this behavior.

Content Model

Permitted Content

One or more <dt> elements
One or more <dd> elements
The <dt> elements should come before <dd> elements

Required Parent

Must be a direct child of <dl>.

Related Elements

<dl> - Description list container (required parent)
<dt> - Definition term (the key/label)
<dd> - Definition description (the value)

Patterns Using This Element

The <dl-item> element is designed specifically for these patterns:

Key-Value / Description List

Display key-value pairs in horizontal or stacked layouts