dl-item
Groups a dt/dd pair within a description list for built-in layout variants.
Description
The <dl-item> custom element groups a <dt>/<dd> pair within a <dl> for styling. Apply class variants on the parent <dl> to get built-in layouts — no custom CSS needed.
Variants
| Class | Description |
|---|---|
.horizontal |
Side-by-side key-value rows (grid layout) |
.stacked |
Label above value (flex column) |
.bordered |
Separator lines between items |
.compact |
Tight spacing for dense data |
data-striped |
Alternating row backgrounds |
Variants compose freely — combine .horizontal, .bordered, and .compact on a single <dl>.
Horizontal
Side-by-side key-value pairs. Combine with .bordered for separator lines between rows.
<dl class="horizontal bordered"> <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>Role</dt> <dd>Senior Engineer</dd> </dl-item> <dl-item> <dt>Status</dt> <dd>Active</dd> </dl-item></dl>Stacked
Label above value with muted term styling. Good for metadata or profile fields.
<dl class="stacked"> <dl-item> <dt>Project</dt> <dd>Vanilla Breeze Design System</dd> </dl-item> <dl-item> <dt>Description</dt> <dd>A classless, HTML-first CSS framework with custom elements and design tokens.</dd> </dl-item> <dl-item> <dt>License</dt> <dd>MIT</dd> </dl-item></dl>Compact
Tighter spacing for dense data. Combine with .horizontal and .bordered.
<dl class="horizontal compact bordered"> <dl-item> <dt>Created</dt> <dd>2025-11-15</dd> </dl-item> <dl-item> <dt>Updated</dt> <dd>2026-02-28</dd> </dl-item> <dl-item> <dt>Version</dt> <dd>1.4.0</dd> </dl-item></dl>Striped
Alternating row backgrounds using the data-striped attribute — the same attribute used on plain <dl> elements.
<dl class="horizontal" data-striped> <dl-item> <dt>CPU</dt> <dd>Apple M2 Pro</dd> </dl-item> <dl-item> <dt>Memory</dt> <dd>32 GB</dd> </dl-item> <dl-item> <dt>Storage</dt> <dd>1 TB SSD</dd> </dl-item> <dl-item> <dt>Display</dt> <dd>14-inch Liquid Retina XDR</dd> </dl-item></dl>Multiple Values
A single <dl-item> can hold one <dt> with multiple <dd> elements.
<dl class="horizontal bordered"> <dl-item> <dt>Phone Numbers</dt> <dd>+1 (555) 123-4567</dd> <dd>+1 (555) 987-6543</dd> </dl-item></dl>Why a Custom Element?
HTML5 allows wrapping <dt>/<dd> pairs in <div>, but <dl-item> is more specific than <div> in both CSS selectors and code readability. It describes its purpose — grouping a description list item — without carrying the ambiguity of a generic container.
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>.