Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
Description List
Display key-value pairs using semantic HTML description lists. Perfect for detail panels, settings displays, and profile information.
Overview
Description lists provide a structured way to present pairs of labels and values. Using the semantic <dl>, <dt>, and <dd> elements ensures proper accessibility and document structure while providing flexibility for visual styling.
Key features:
- Semantic HTML for accessibility and SEO
- Flexible layouts: vertical stacking or horizontal rows
- Grouped sections for organized data presentation
- Consistent styling with muted labels and clear values
- Responsive design that adapts to screen size
- Uses
@scopefor encapsulated, semantic CSS selectors
Simple Vertical Layout
A basic vertical description list with terms stacked above their descriptions. The <dl-item> custom element groups each <dt>/<dd> pair.
Simple vertical description list
<dl class="key-value" data-layout="stacked"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Email Address</dt> <dd>[email protected]</dd> </dl-item> <dl-item> <dt>Phone Number</dt> <dd>+1 (555) 123-4567</dd> </dl-item> <dl-item> <dt>Status</dt> <dd> <span class="badge success">Active</span> </dd> </dl-item></dl>Stacked Layout Styles
Stacked description list CSS
@scope (.key-value[data-layout="stacked"]) { :scope { margin: 0; display: flex; flex-direction: column; gap: var(--size-l); } dl-item { display: flex; flex-direction: column; gap: var(--size-2xs); } dt { font-size: var(--font-size-sm); color: var(--color-text-muted); } dd { margin: 0; font-size: var(--font-size-md); }}Horizontal Layout
A horizontal layout with labels on the left and values on the right. This format works well for detail panels, settings pages, and profile information where you want to scan labels quickly.
Horizontal description list
<dl class="key-value"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Email</dt> <dd>[email protected]</dd> </dl-item> <dl-item> <dt>Phone</dt> <dd>+1 (555) 123-4567</dd> </dl-item> <dl-item> <dt>Status</dt> <dd> <span class="badge success">Active</span> </dd> </dl-item></dl>Horizontal Layout Styles
Horizontal description list CSS
@scope (.key-value) { :scope { margin: 0; } 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; } dt { font-size: var(--font-size-sm); color: var(--color-text-muted); } dd { margin: 0; }} /* Responsive: stack on small screens */@media (max-width: 480px) { @scope (.key-value) { dl-item { grid-template-columns: 1fr; gap: var(--size-2xs); } }}Grouped Sections
Multiple description lists organized into logical sections with headings. Each section uses a <layout-card> for visual separation. Ideal for profile pages, order details, or settings displays.
Grouped description lists
<layout-stack data-layout-gap="l"> <!-- Personal Information Section --> <layout-card data-padding="l"> <layout-stack data-layout-gap="m"> <h2 class="section-heading">Personal Information</h2> <dl class="key-value"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Date of Birth</dt> <dd>March 15, 1992</dd> </dl-item> </dl> </layout-stack> </layout-card> <!-- Contact Details Section --> <layout-card data-padding="l"> <layout-stack data-layout-gap="m"> <h2 class="section-heading">Contact Details</h2> <dl class="key-value"> <dl-item> <dt>Email</dt> <dd>[email protected]</dd> </dl-item> <dl-item> <dt>Phone</dt> <dd>+1 (555) 123-4567</dd> </dl-item> </dl> </layout-stack> </layout-card></layout-stack>Section Heading Styles
Section heading CSS
.section-heading { margin: 0; font-size: var(--font-size-md); font-weight: var(--font-weight-semibold);}Configuration
Description list patterns use these elements and CSS techniques:
HTML Structure
| Element | Purpose | Description |
|---|---|---|
<dl class="key-value"> |
Container | The description list container. Add data-layout="stacked" for vertical layout. |
<dl-item> |
Row grouping | Custom element that groups a <dt>/<dd> pair for styling. |
<dt> |
Label | The description term (label). |
<dd> |
Value | The description details (value). |
Grid Row Widths
| Label Width | Best For | Description |
|---|---|---|
100px |
Short labels | Works well for single-word labels like "Name", "Email", "Phone" |
140px |
Medium labels | Good balance for labels like "Full Name", "Phone Number" |
180px |
Long labels | Accommodates longer labels like "Email Address", "Member Since" |
CSS Custom Properties
| Property | Usage | Description |
|---|---|---|
--color-text-muted |
Labels (dt) | Subdued color for term labels to create visual hierarchy |
--color-border |
Row separators | Light border color for horizontal row dividers |
--font-size-sm |
Labels (dt) | Smaller font size for term labels |
Usage Notes
- Semantic HTML: Always use
<dl>,<dt>, and<dd>elements for proper accessibility. Screen readers announce these as description lists. - CSS
@scope: Styles use@scope (.key-value)to encapsulate rules and enable semantic element selectors (dl-item,dt,dd) without class pollution. - Item grouping: The
<dl-item>custom element groups each term/description pair. This is valid HTML5 and enables grid layout for horizontal display. - Multiple values: A single
<dt>can have multiple<dd>elements for multiple values (e.g., multiple phone numbers). - Responsive design: The horizontal layout uses a media query to stack on smaller screens, switching from grid to single-column display.
- Value formatting: Use badges, icons, or formatted text in
<dd>elements to enhance readability. - Empty values: Display a dash or "Not provided" for empty values rather than leaving blank.
- Long values: For long text values, consider truncation with a "show more" toggle or allowing text to wrap naturally.
- Actions: You can include edit links or buttons within
<dd>elements for inline editing capabilities.
Related
Stats
Metric cards and stat displays
Profile
User profile pages with description lists
Settings
Settings pages with grouped options