Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 122 ยท Lists

Description Lists

Use dl, dt and dd to build glossaries, FAQs and key-value details. Learn how to group several terms and descriptions, wrap groups in div and style them.

Some information comes in pairs: a word and its definition, a question and its answer, a label and its value. "Weight: 1.2 kg." "Author: Ada Brooks." "Latency: the time a request takes to travel to the server and back." Bullets and numbers don't fit that shape. A description list does.

A description list, <dl>, groups names with their values. This lesson shows the three elements involved, the rules for combining them, and the most useful real-world patterns: glossaries, product details and metadata.

The three elements

Element Name Role
<dl> description list Wraps the whole list.
<dt> description term The name: a term, a label, a question.
<dd> description details The value: a definition, a description, an answer.
A small glossary

By default, browsers show each <dt> on its own line and indent the <dd> below it. There are no bullets or numbers. The pairing itself is the structure.

The standard lets you leave out </dt> and </dd>, but in this course you should always write them, just as with list items. The blank lines between groups are optional too. They are only there to make the source easier to scan, and the browser ignores them like any other whitespace. Try adding a fourth coffee term to the glossary, with its own <dt> and <dd> pair.

"Definition list" is the old name. Older tutorials call <dl> a definition list. Since HTML5 it is officially a description list, because it's used for much more than dictionary definitions: any group of name-value pairs fits.

Several terms, several descriptions

A group doesn't have to be exactly one <dt> and one <dd>. The rule is: one or more <dt> elements, followed by one or more <dd> elements.

  • Several <dt> elements before a <dd> mean the terms share that description, which is useful for synonyms or alternative spellings.
  • Several <dd> elements after a <dt> mean the term has several values or meanings.
Groups with several terms or values

"Color" and "Colour" share one definition. "Bank" has two meanings. And "Authors" is a label with three values, one per <dd>. That last pattern is common on real pages, as you will see next.

Key-value metadata

Description lists aren't just for glossaries. Any time you would naturally write "Label: value" on several lines, consider a <dl>. Product specifications, order summaries, profile details and article metadata are all good fits:

HTML
<h3>Trail Runner 2 โ€“ specifications</h3>
<dl class="specs">
  <dt>Weight</dt>
  <dd>280 g</dd>

  <dt>Drop</dt>
  <dd>6 mm</dd>

  <dt>Sizes</dt>
  <dd>EU 36โ€“47</dd>

  <dt>Colors</dt>
  <dd>Forest green</dd>
  <dd>Slate gray</dd>
</dl>

Compared with a list of lines like "Weight: 280 g", the <dl> keeps the label and value as separate elements. That makes them easy to style as two columns, and screen readers can announce the structure. A <dl> is usually simpler than a table for this kind of data. Reach for a table when you have several columns of values, such as comparing three shoes side by side.

The structure is machine-readable

Because each label and value live in their own elements, scripts can read them back as data. That is useful for anything from a "copy details" button to automated tests. The example below turns a <dl> into an object and prints it:

Reading a dl as data

Try the same with a paragraph that says "Room: Harbor Suite". You would have to split strings on colons and hope nobody types a colon in a value. Good structure saves work later.

FAQs and questions with answers

A list of questions and answers is a natural fit for a <dl>: each question is a term, each answer its description. The answer can be as rich as you like, with paragraphs, links and lists inside the <dd>.

An FAQ as a description list

For a long FAQ where visitors only need one or two answers, collapsible sections built with <details> and <summary> can be friendlier, because each answer stays hidden until requested. See Details and Summary. For a short FAQ that people will read top to bottom, a description list keeps everything visible and simple.

Grouping with <div>

You may wrap each name-value group in a <div>. It changes nothing for meaning, but it gives you a box to style: a border around each pair, a grid of cards, or a row in a two-column layout.

Styled groups with div wrappers

The rules for the wrapper:

  • A <div> inside a <dl> must contain whole groups: one or more <dt> followed by one or more <dd>.
  • If you use <div> wrappers, wrap every group. Don't mix wrapped and unwrapped groups in the same list.
  • Only <div> is allowed as a wrapper; <section>, <span> and other elements aren't.

A side-by-side layout without wrappers

You don't always need wrappers. CSS Grid can put each term and description on one row with just two rules:

Two-column details with CSS Grid

This works neatly when every term has exactly one description. With several <dd> per term, the grid can get out of step, and the <div> wrapper approach is easier.

What goes where

  • <dt> usually holds short content: a word, a label, a question. Headings, sectioning elements, <header> and <footer> aren't allowed inside it.
  • <dd> can hold rich content: paragraphs, lists, images, even another <dl>.
  • The only direct children of <dl> are <dt>, <dd> and <div> (plus <script> and <template>).
HTML
<dl>
  <dt><dfn>Cache</dfn></dt>
  <dd>
    <p>A store of copies kept close by, so they can be reused quickly.</p>
    <p>Browsers cache images and stylesheets to make return visits faster.</p>
  </dd>
</dl>

Wrapping a term in <dfn> marks it as the place where the term is defined, which is a nice touch in a glossary. You will meet <dfn> again in Quotations, Citations and Abbreviations.

Don't use <dl> just for indentation. Because <dd> is indented by default, old pages used <dl> to push text to the right. That gives screen readers a false structure. Use CSS margin or padding for indentation.

Choosing between <dl>, <ul> and <table>

All three can hold "lists of things", so it helps to have a quick test:

  • One label per value, read top to bottom? Use <dl>. Specifications, contact details, glossaries.
  • A set of similar items without labels? Use <ul> or <ol>. Features, steps, links.
  • Several values per row that people compare across columns? Use a table. A price comparison, a timetable, a scoreboard.

If you are tempted to write <li><strong>Weight:</strong> 280 g</li> for every line, that is a sign the content is really a description list.

Screen reader support varies. Some screen readers announce a description list and count its terms; others read it more like ordinary text. Either way, the content stays in a sensible order, and the clear structure still helps search engines, scripts and your CSS. Write good, short terms so each pair makes sense when heard aloud.

Common mistakes

  • Putting <dd> before its <dt>. The name always comes first.
  • Leaving out <dt> entirely. A <dd> with no term in front of it has nothing to describe.
  • Wrapping some groups in <div> but not others. Wrap all or none.
  • Adding colons inside <dt>. "Weight:" reads oddly to a screen reader and makes the term harder to reuse. If you want a colon, add it with CSS: dt::after { content: ":"; }.
  • Using <li> inside a <dl>. List items belong to <ul> and <ol> only.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element holds the value or description in a description list?

    <dd> (description details) holds the value. <dt> holds the term or name, and <li> belongs to <ul> and <ol>.
  2. 2. Two spellings of a word share one definition. How do you mark that up?

    A group may start with several terms; they all share the descriptions that follow.
  3. 3. Which element may wrap a whole term-and-description group inside a dl?

    Only <div> may wrap groups in a <dl>, and if you use it, every group should be wrapped.
  4. 4. Which content suits a description list best?

    Specifications are label-value pairs, which is exactly what <dl> is for. Steps belong in <ol>, and menus in <ul>.

Summary

  • <dl> is a list of name-value groups: <dt> for the name, <dd> for the value.
  • A group is one or more <dt> followed by one or more <dd>.
  • Use it for glossaries, FAQs, specifications, order summaries and other metadata.
  • You may wrap each group in a <div> for styling; wrap all groups or none.
  • <dd> can contain rich content; keep <dt> short, and never put headings inside it.

Next lesson: Nested Lists.