dl
The description list element represents a collection of term-description pairs, such as glossaries, metadata, or key-value data.
Description
The <dl> element (description list, formerly "definition list") contains groups of terms (<dt>) and their descriptions (<dd>). It represents an association list of name-value pairs.
Unlike <ul> and <ol>, which use <li> elements, definition lists use the <dt> and <dd> pair structure.
When to Use
- Glossaries — Terms and definitions
- Metadata — Author, date, category displays
- FAQ sections — Question-answer pairs
- Product specifications — Specs and details
- Contact information — Label-value pairs
When Not to Use
Basic Usage
A basic definition list with single term-description pairs.
<dl> <dt>HTML</dt> <dd>HyperText Markup Language — the standard markup language for documents.</dd> <dt>CSS</dt> <dd>Cascading Style Sheets — a style sheet language for presentation.</dd> <dt>JavaScript</dt> <dd>A programming language that enables interactive web pages.</dd></dl>Multiple Descriptions
A single term can have multiple descriptions. Useful for words with multiple meanings or items with several explanations.
<dl> <dt>Set</dt> <dd>A collection of distinct objects considered as a whole.</dd> <dd>To put something in a specified place or position.</dd> <dd>A group of games in tennis forming part of a match.</dd> <dt>Run</dt> <dd>Move at a speed faster than walking.</dd> <dd>An instance of a program being executed.</dd></dl>Multiple Terms
Multiple terms can share a single description. Useful for synonyms, abbreviations, or alternate names.
<dl> <dt>World Wide Web</dt> <dt>WWW</dt> <dt>The Web</dt> <dd>An information system enabling documents and other web resources to be accessed over the Internet.</dd></dl>Metadata Display
Definition lists are excellent for displaying metadata or properties in a structured way.
<dl> <dt>Author</dt> <dd>Jane Smith</dd> <dt>Published</dt> <dd><time datetime="2024-01-15">January 15, 2024</time></dd> <dt>Category</dt> <dd>Technology</dd> <dt>Reading Time</dt> <dd>5 minutes</dd></dl>Product Specifications
Definition lists work well for product specs and technical details.
Striped Variant
Add the data-striped attribute for alternating row backgrounds, making it easier to scan long definition lists. This mirrors the table.striped pattern.
<dl data-striped> <dt>Dimensions</dt> <dd>10" x 8" x 2"</dd> <dt>Weight</dt> <dd>2.5 lbs (1.13 kg)</dd> <dt>Material</dt> <dd>Aluminum alloy</dd> <dt>Colors Available</dt> <dd>Silver, Space Gray, Gold</dd> <dt>Warranty</dt> <dd>2 years limited</dd></dl>Comparison: dl vs ul/ol
| Feature | <dl> |
<ul>/<ol> |
|---|---|---|
| Structure | Term-description pairs | Single items |
| Child elements | <dt>, <dd> |
<li> |
| Best for | Key-value data, glossaries | Lists of items |
| Markers | None (styled with indentation) | Bullets or numbers |
| Order significance | No | <ol>: yes, <ul>: no |
CSS Properties
dl { display: block;} dt { font-weight: 600;} dd { margin-inline-start: var(--size-l);} dd + dt { margin-block-start: var(--size-m);} /* Striped variant */dl[data-striped] dt,dl[data-striped] dd { padding-inline: var(--size-s); padding-block: var(--size-2xs);} dl[data-striped] dt:nth-of-type(odd),dl[data-striped] dt:nth-of-type(odd) + dd { background: var(--color-surface-raised);}Accessibility
Screen Reader Behavior
- Announced as "description list" with item count
- Terms (
<dt>) announced as labels or keys - Descriptions (
<dd>) announced as associated values - Users can navigate between term-description groups
Grouping with div
HTML5 allows wrapping <dt>/<dd> pairs in <div> for styling purposes. This is especially useful with the striped variant when terms have multiple descriptions.
<dl> <div> <dt>Term One</dt> <dd>Description one</dd> </div> <div> <dt>Term Two</dt> <dd>Description two</dd> </div></dl>