Description Lists

A description list pairs names with their meanings or values, such as a glossary or a menu with prices, using dl for the list, dt for each name and dd for what it means.

Apprentice · HTML · Updated

After this lesson you can

  • Write a description list with dl, dt and dd for names and their meanings
  • Choose a description list when each item pairs a name with its meaning or value

Key takeaways

  • A description list holds pairs of a name and what goes with it, such as a word and its meaning, or a menu item and its price.
  • Write the list in <dl>, each name in a <dt> and its description in a <dd> right after it.
  • One name can have more than one <dd>, and several names can share one <dd>.
  • Inside a <dl>, only <dt> and <dd> elements go directly, or a <div> that wraps one group of them.

Some lists aren't a list of things, but a list of pairs. The glossary at the back of a textbook pairs each word with its meaning. A café menu pairs each drink with its price. A product page pairs "Weight" with "2 pounds" and "Color" with "Midnight blue". You'll meet this shape everywhere: a FAQ, a contact card, the specs of a phone, the details of an order. HTML has a list made for it.

Names and what goes with them

Picture the glossary of game words on the Galaxy Blasters arcade's website. Each entry has two parts: a word, such as token, and its meaning, a coin you buy at the front desk to start a game. A plain bulleted list would lose the line between the two parts: a screen reader would read each entry as one long sentence.

A list of name-and-description pairs is called a description list. Each name in it is a description term, and each description is a description details. The "description" can be a definition, a value, a price or an answer: anything that belongs to the name.

In older books and tutorials you may see it called a definition list, its name in early versions of HTML. It was renamed because it holds much more than definitions.

dl, dt and dd

Three elements build a description list:

  • <dl>, read "D L": the description list around the whole thing.
  • <dt>, read "D T": a description term, the name.
  • <dd>, read "D D": the description details, what goes with the name.

Each <dt> comes first, and its <dd> follows right after it:

<h2>Arcade words</h2>
<dl>
    <dt>Token</dt>
    <dd>A coin you buy at the front desk to start a game.</dd>
    <dt>High score</dt>
    <dd>The best score anyone has reached on a machine.</dd>
    <dt>Extra life</dt>
    <dd>One more ship, so the game goes on after you're hit.</dd>
</dl>

The browser shows each term on its own line and each description indented under it, with no bullets or numbers. The look is plain on purpose; CSS can make it look like anything. What matters is that the HTML says which part is the name and which is its description, so a screen reader can announce them as a pair.

Try it. In your practice folder, make arcade-words.html from the page skeleton, and add the list above. Then add two words of your own from a game you like, such as boss or checkpoint.

Values, not only definitions

A description doesn't have to be a definition. The arcade's snack bar uses a description list for its menu, pairing each snack with its price:

<h2>Snack bar</h2>
<dl>
    <dt>Nachos with cheese</dt>
    <dd>$4.50</dd>
    <dt>Rocket Pop</dt>
    <dd>$2.00</dd>
    <dt>Popcorn bucket</dt>
    <dd>$3.25</dd>
</dl>

The same shape fits any set of names with one value each: a game cabinet's details (Players: 1 or 2, Cost: 1 token), the opening hours on a contact page, or the details on an order confirmation (Order number, Delivery date).

More than one description, or more than one name

Pairs aren't always one to one. One term can have several <dd> elements, and several terms can share one <dd>:

<dl>
    <dt>Galaxy Slush</dt>
    <dd>Blue raspberry or cherry.</dd>
    <dd>$3.00</dd>
    <dt>Boss</dt>
    <dt>Mothership</dt>
    <dd>The giant enemy at the end of each level.</dd>
</dl>

Galaxy Slush has two descriptions: its flavors and its price. Boss and Mothership are two names for the same thing, so they share one description. Each <dd> belongs to the <dt> (or the group of <dt> elements) above it.

What goes inside a dl

The <dl> holds only <dt> and <dd> elements directly. There's one exception: you may wrap each group, a term and its descriptions, in a <div>, a box with no meaning that's handy for styling a group later. A paragraph, a heading or an <li> doesn't go directly inside a <dl>. Put headings above the list, and other elements inside a <dd>:

<dl>
    <div>
        <dt>Shield Bubble</dt>
        <dd>Blocks the next <strong>three</strong> hits.</dd>
    </div>
</dl>

Which list is it?

You now have three lists, and the question to ask is about each item:

  • Is each item one thing, and the order doesn't matter? A <ul>: the games on the floor.
  • Is each item one thing, and the order matters? An <ol>: the steps to play, the top 10.
  • Is each item a name with something that goes with it? A <dl>: arcade words and their meanings, snacks and their prices.

When each name has several values that line up in columns, such as a snack's price in small, medium and large, the content has outgrown a list: that's a table, the next lesson's subject.

Try it. Add the snack bar menu to arcade-words.html, with a snack that has two descriptions: its flavors and its price.

Check yourself

2 questions to try on the lesson page.

So what

Glossaries, menus, specs and order details are all pairs of a name and its value. A description list keeps each pair together, so readers, screen readers and search engines can tell which description belongs to which name.

Key terms

Cheat sheets

Related