HTML Description Lists

Description Lists Overview

The description list - the dl element - is the least used of the three HTML list types and also the most misunderstood, which is a shame because it's genuinely the right semantic tool for a whole category of content that people often end up marking up with tables or divs instead. The concept is simple: a list where each item has two parts, a term and its description, rather than just a single item. Glossaries, FAQs, product specs, metadata panels - any time you have a consistent label-then-value or question-then-answer structure, a dl probably fits better than whatever else you were about to use.

Key Components

  • <dl> - The outer container for the entire description list - equivalent to ul or ol for regular lists.
  • <dt> - Description Term - the label, question, or name in each pair. There can be multiple dt elements before a single dd if several terms share the same description.
  • <dd> - Description Details - the value, answer, or definition that follows the term. Multiple dd elements can follow one dt if a term has several associated values.

Basic Syntax

The structure is dl as the wrapper, then dt and dd pairs inside it - each dt followed by its dd, as many pairs as you need. The browser's default rendering indents the dd elements under the dt elements, creating a visual pairing, though you'll almost certainly want to style this yourself in any real project.

html
1<dl>
2  <dt>HTML</dt>
3  <dd>HyperText Markup Language, the standard language for creating web pages.</dd>
4  
5  <dt>CSS</dt>
6  <dd>Cascading Style Sheets, used to describe the presentation of HTML documents.</dd>
7  
8  <dt>JavaScript</dt>
9  <dd>A programming language that enables interactive web pages.</dd>
10</dl>

Browser Default Rendering

  • HTML - HyperText Markup Language, the standard language for creating web pages.
  • CSS - Cascading Style Sheets, used to describe the presentation of HTML documents.
  • JavaScript - A programming language that enables interactive web pages.

Advanced Usage Patterns

The dl element is more flexible than most people realize - you can have multiple dt elements pointing to one dd (for terms with aliases or alternate names), multiple dd elements following one dt (for terms with several related values), and combinations of both in the same list. This flexibility makes it work well for content like API documentation where a method might have several names and several related descriptions.

html
1<!-- Multiple terms for one description -->
2<dl>
3  <dt>HTML</dt>
4  <dt>HyperText Markup Language</dt>
5  <dd>The standard markup language for documents designed to be displayed in a web browser.</dd>
6</dl>
7
8<!-- Multiple descriptions for one term -->
9<dl>
10  <dt>API</dt>
11  <dd>Application Programming Interface</dd>
12  <dd>A set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.</dd>
13</dl>
14
15<!-- Multiple terms and multiple descriptions -->
16<dl>
17  <dt>Front-end</dt>
18  <dt>Client-side</dt>
19  <dd>HTML</dd>
20  <dd>CSS</dd>
21  <dd>JavaScript</dd>
22  
23  <dt>Back-end</dt>
24  <dt>Server-side</dt>
25  <dd>Node.js</dd>
26  <dd>Python</dd>
27  <dd>PHP</dd>
28</dl>

Usage Patterns

  • Multiple terms, one description - Stack multiple dt elements before a single dd when several terms share the same meaning - useful for abbreviations alongside their full forms.
  • Multiple descriptions, one term - Stack multiple dd elements after a single dt when a term has several related values or aspects worth listing separately.
  • Mixed groupings - Combine multiple terms and multiple descriptions in the same list when the content structure calls for it - though this gets confusing quickly so keep it simple.

Practical Use Cases

The dl element shows up in more places than you might expect once you start looking for term-description relationships in real content - and it's often replacing a table or a grid of divs that would work but carries less semantic meaning.

html
1<!-- FAQs -->
2<dl class="faq">
3  <dt>What is your return policy?</dt>
4  <dd>We accept returns within 30 days of purchase with original receipt.</dd>
5  
6  <dt>Do you offer international shipping?</dt>
7  <dd>Yes, we ship to over 50 countries worldwide.</dd>
8</dl>
9
10<!-- Product metadata -->
11<dl class="product-info">
12  <dt>SKU</dt>
13  <dd>PRD-29482</dd>
14  
15  <dt>Dimensions</dt>
16  <dd>24 × 16 × 8 cm</dd>
17</dl>
18
19<!-- Technical specifications -->
20<dl class="specifications">
21  <dt>Processor</dt>
22  <dd>Intel Core i7-1165G7</dd>
23  
24  <dt>Memory</dt>
25  <dd>16GB DDR4</dd>
26</dl>
27
28<!-- Interview or dialogue -->
29<dl class="conversation">
30  <dt>Interviewer</dt>
31  <dd>What inspired you to pursue this career?</dd>
32  
33  <dt>Interviewee</dt>
34  <dd>I've always been fascinated by how technology can solve real-world problems.</dd>
35</dl>

Use Cases

  • FAQs - Questions as dt, answers as dd - the structure maps perfectly and screen readers get semantic context about the relationship.
  • Product metadata and specs - Label-value pairs like SKU, dimensions, weight, and material are exactly what dl was designed for.
  • Technical specifications - Configuration settings, hardware specs, API parameter descriptions - any consistent key-value structure.
  • Dialogue and conversations - Speaker names as dt, their lines as dd - a less common use but semantically valid for transcripts and interview content.

Styling with CSS

The browser default styling for dl is fine for simple glossaries but for product specs and metadata panels you usually want a horizontal side-by-side layout where the term and description are on the same line. CSS grid makes this cleaner than it used to be - before grid you'd have to float or inline-block the dt and dd elements which got awkward with varying content lengths.

css
1/* Basic vertical layout */
2dl {
3  margin: 1em 0;
4  line-height: 1.5;
5}
6dt {
7  font-weight: bold;
8  margin-top: 1em;
9}
10dd {
11  margin-left: 2em;
12  color: #555;
13}
14
15/* Horizontal label-value layout using grid */
16dl.horizontal {
17  display: grid;
18  grid-template-columns: max-content auto;
19  gap: 0.5em 1em;
20}
21dl.horizontal dt {
22  grid-column: 1;
23  font-weight: bold;
24  margin: 0;
25}
26dl.horizontal dd {
27  grid-column: 2;
28  margin: 0;
29}
30
31/* FAQ layout with Q: and A: prefixes */
32dl.faq dt {
33  position: relative;
34  padding-left: 2em;
35  margin-top: 1.5em;
36}
37dl.faq dt::before {
38  content: "Q: ";
39  font-weight: bold;
40  color: #e74c3c;
41  position: absolute;
42  left: 0;
43}
44dl.faq dd {
45  padding-left: 2em;
46  margin-bottom: 0.5em;
47}
48dl.faq dd::before {
49  content: "A: ";
50  font-weight: bold;
51  color: #2ecc71;
52}

Styling Approaches

  • Basic vertical - Bold terms stacked above indented descriptions. The browser default, slightly cleaned up.
  • Horizontal grid layout - Terms and descriptions side by side using CSS grid. Good for product specs and metadata where space is limited.
  • FAQ layout - Q: and A: prefixes injected with CSS ::before pseudo-elements so the HTML stays clean.

Best Practices

The core rule for description lists is to use them for genuine term-description relationships, not just to get a two-column visual layout. If you're reaching for dl because you want something that looks like a label next to a value, that's the right instinct - but make sure the relationship is semantically meaningful, not just visual. Also worth knowing: dl should only contain dt and dd elements as direct children, not arbitrary div elements wrapping pairs (though the HTML5 spec does allow wrapping dt/dd pairs in a div for styling purposes in some cases).

Key Guidelines

  • Use for real term-description pairs - The dt and dd should have a genuine semantic relationship - not just two pieces of content that happen to sit next to each other visually.
  • Keep terms and descriptions concise - Long paragraphs in dd elements work but description lists read best when terms are short and descriptions are focused.
  • Don't use for layout - Using dl just to get a two-column layout with no semantic meaning behind the pairing is misuse. CSS grid or flexbox handles layout without the semantic baggage.
  • Consider the horizontal layout for dense data - For product specs and metadata with many short pairs, the CSS grid horizontal layout is much more compact and readable than the default stacked style.

When to Use Description Lists

The quick decision guide: if you have a list of things and each thing is just a single item, use ul or ol. If you have data that belongs in rows and columns with headers, use table. If you have pairs of related information where one part is a label or term and the other is a value or explanation, use dl. The dl is the one that gets skipped most often in favor of tables or custom div structures, usually because developers aren't sure it fits - but for anything that looks like a glossary, an FAQ, or a product spec sheet, it almost certainly does.

html
1<!-- Use dl for: glossaries, FAQs, product specs, metadata -->
2<dl>
3  <dt>Term or label</dt>
4  <dd>Definition, answer, or value</dd>
5</dl>
6
7<!-- Use ul or ol for: simple item lists without paired descriptions -->
8<ul>
9  <li>Just an item</li>
10</ul>
11
12<!-- Use table for: data with multiple columns and clear row/column relationships -->
13<table>...</table>

The Overlooked List That's Actually Useful

Description lists solve a specific problem well - structured pairs of related information - and they've been part of HTML since early versions even though they stay under the radar compared to ul and ol. The semantic benefit over using a table or a bunch of styled divs is real: screen readers understand the term-description relationship and announce it appropriately, search engines get clearer context about the paired content, and the HTML is cleaner to read and maintain. Worth reaching for whenever the content has that natural label-value structure

Frequently Asked Questions

Can I use other HTML elements inside dt and dd tags?

Yes. Both dt and dd can contain inline and block-level elements - paragraphs, images, lists, links, code snippets, whatever the content requires. Dt is typically short (a term or label) but there's no rule against longer content. Dd can contain as much rich content as needed, which makes description lists work for complex FAQ answers that include code examples or multiple paragraphs.

How do screen readers handle description lists?

Screen readers announce description lists differently from regular lists - they identify terms and descriptions as paired and often announce something like 'term' before reading the dt and 'definition' before reading the dd. This gives users navigating by screen reader meaningful context about the relationship between the paired content, which is the main semantic advantage over a visually similar table or div layout.

Can I nest description lists?

Technically yes but it's rarely useful and creates confusing semantics. If you find yourself wanting nested description lists, it's usually a sign the content could be organized differently - either as separate dl elements under their own headings, or as a structure where some items in a dl have rich dd content including nested lists of another type.

Are there accessibility concerns when styling description lists?

The main one is maintaining the visual connection between terms and their descriptions when using custom layouts. With the horizontal CSS grid approach especially, make sure the visual pairing is clear even on narrow screens where the grid might collapse. Also avoid styling that breaks the visual order - if a dt and its dd aren't visually adjacent, users without screen readers lose the pairing context that makes the list useful.

What is the difference between dl and a two-column table?

Both can display paired information visually but they communicate different things semantically. A table implies that the data has row and column relationships and can be navigated as a grid. A description list implies a set of term-description pairs where each pair is independent of the others. For a glossary or FAQ, dl is the more accurate semantic choice. For data where users might want to compare values across rows, table is more appropriate.