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.

Semantic Meaning

A description list conveys that:

  • Content consists of related name-value or term-description pairs
  • Terms (<dt>) are keys or labels
  • Descriptions (<dd>) are values or explanations
  • Each term can have multiple descriptions, and vice versa

Screen readers can announce the relationship between terms and descriptions, helping users understand the data structure.

When to Use

  • Glossaries with terms and definitions
  • Metadata displays (author, date, category)
  • FAQ sections (question-answer pairs)
  • Product specifications
  • Contact information (label-value pairs)
  • Any key-value or term-description data

When Not to Use

  • For simple sequential items - use <ol>
  • For unordered collections - use <ul>
  • For tabular data with multiple columns - use <table>
  • For dialog/conversation markup - use other semantic elements

Basic Usage

A basic definition list with single term-description pairs.

HTML
HyperText Markup Language - the standard markup language for documents designed to be displayed in a web browser.
CSS
Cascading Style Sheets - a style sheet language used for describing the presentation of a document.
JavaScript
A programming language that enables interactive web pages and is an essential part of web applications.
<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. This is useful for words with multiple meanings or items with several explanations.

Set
A collection of distinct objects considered as a whole.
To put something in a specified place or position.
A group of games in tennis forming part of a match.
Run
Move at a speed faster than walking.
An instance of a program being executed.
<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. This is useful for synonyms, abbreviations, or alternate names.

World Wide Web
WWW
The Web
An information system enabling documents and other web resources to be accessed over the Internet.
URL
Uniform Resource Locator
Web Address
A reference to a web resource that specifies its location on a computer network.
<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.

Author
Jane Smith
Published
Category
Technology
Reading Time
5 minutes
Tags
HTML, CSS, Web Development
<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.

Dimensions
10" x 8" x 2"
Weight
2.5 lbs (1.13 kg)
Material
Aluminum alloy
Colors Available
Silver, Space Gray, Gold
Warranty
2 years limited

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

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

Best Practices

  • Use for genuine term-description relationships
  • Keep terms concise and descriptive
  • Ensure descriptions provide meaningful information
  • Maintain logical grouping of <dt>/<dd> pairs
  • Consider using <div> to group term-description pairs for styling (HTML5 allows this)

Grouping with div

HTML5 allows wrapping <dt>/<dd> pairs in <div> for styling purposes.

<dl> <div> <dt>Term One</dt> <dd>Description one</dd> </div> <div> <dt>Term Two</dt> <dd>Description two</dd> </div> </dl>

CSS Properties

Element Property Value
<dl> display block
<dt> font-weight 600
<dd> margin-inline-start var(--size-l)
<dd> + <dt> margin-block-start var(--size-m)

Related Elements

  • <dt> - Definition term (the key/name)
  • <dd> - Definition description (the value)
  • <dl-item> - Custom element for grouping dt/dd pairs
  • <ul> - Unordered list (for simple item collections)
  • <ol> - Ordered list (for sequential items)

Patterns Using This Element

The <dl> element serves as the semantic foundation for these patterns:

Key-Value / Description List

Display key-value pairs in horizontal or stacked layouts