#30DaysofHTML Day 5: Description lists and < dl >, < dt >, < dd >

Key-value pairs in a list

Today we focus on the three elements that make up a description list, historically called the definition list: <dl>, <dt>, and <dd>.

While ordered <ol> and unordered <ul> lists are made of a series of single items, a description list has pairs of information. If there is a RELATIONSHIP between the term and the details, then you can technically use a description list.

The meaning of each tag is as follows:

• <dl> description list (or definition list)

• <dt> description name (or definition term)

• <dd> description details (or definition)

(The above would be best marked up with a definition list. Unfortunately, we cannot access the Substack code to make it so. Yep, we’re as guilty of bad markup as anyone else.)

Typically, a description list might be used with many types of information:

📚 Author and book title(s)

📷 Location and photographer

🕸 Website and description

🎪 Date and event

❓(Frequently Asked) Question and answer

You might also use it for some specific metadata at the start of an article or a recipe.

Examples of a description list

A more general use is as a description list. Here we have two stores and things to purchase at each one:

<dl>
   <dt>Target</dt>
     <dd>dish soap</dd>
     <dd>socks</dd>
   <dt>Fresh Thyme</dt>
     <dd>coconut water</dd>
     <dd>strawberries</dd>
     <dd>aged gouda</dd>
</dl> 

The classic use as a definition list consisting of terms and definitions still works. It's lovely. Don't forget to include the <dfn> tag as appropriate!:

<dl>
   <dt><dfn>Target</dfn></dt>
   <dd>Chain of stores selling clothing, electronics, health supplies and general household items</dd>
   <dt><dfn>Fresh Thyme</dfn></dt>
   <dd>A Midwestern grocery store chain in the United States</dd> 
</dl> 

Duplicating terms and descriptions

As shown above, you may have more than one <dt> for a <dd>, and you may have more than one <dd> for a <dt>.

If you have multiple <dt> elements in a row, it's assumed these are all names for the same thing.

If you have multiple <dd> elements in a row, it's assumed these are all possible descriptions for the term(s) immediately preceding the description.

See our CodePen for more examples of definition lists.

Little known fact about description lists

WHATWG is permitting <div> elements inside of <dl> now for two purposes: styling and for holding microdata elements. Check our CodePen example for some ways that these <div> elements impact styling - even without holding a class attribute!

<h3>Grandma's Apple Pie</h3> 
 <dl>
   <div>
     <dt>Preparation time</dt>
     <dd>1 hour</dd>
   </div>
   <div>
     <dt>Baking time</dt>
     <dd>45 minutes</dd>
   </div>
   <div>
     <dt>Oven temperature</dt>
     <dd>350 degrees</dd>
   </div>
 </dl>

Description list demo

🖥 View the description list demo on CodePen.

Quiz: What could be marked up as a description list?

🧪 Take the quiz and find out! There’s only one question, and it should take you less than 2 minutes to complete.

Challenge: Using description lists

👩🏽‍💻 Try today’s CodePen Challenge about the use of description lists. When you’ve completed it, post your answer in our discussion in Substack.

More information and examples

📚 MDN: <dl>, <dt>, <dd>

📚 WHATWG: <dl> (keep scrolling for <dt> and <dd>)

📚 Adrian Roselli on screen readers and description lists

📚 CSS-Tricks: Utilizing the Underused (But Semantically Awesome) Definition List