The dl element

The <dl> element existed in HTML 4, but it’s been repurposed in HTML5. Let the Doctor explain what’s changed and how it can be used.

It’s all in the description

In HTML 4, <dl> was considered a “definition list”, containing groups of terms and their definitions. The terms and definitions were a many-to-many relationship: one or more terms to one or more definitions. The element was often misunderstood and therefore misused or not used at all in favour of more widely used and (perhaps) less semantic markup.

To address these issues, <dl>’s definition has been refined in HTML5 as a description list. From the spec:

The dl element represents an association list consisting of zero or more name-value groups (a description list). A name-value group consists of one or more names (dt elements) followed by one or more values (dd elements), ignoring any nodes other than dt and dd elements. Within a single dl element, there should not be more than one dt element for each name.

Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.

It maintains the many-to-many relationship between names and values. These groupings use <dt> to represent the term or name and <dd> for the description. Also note the last line of the quote, stating that a name should not be used more than once within a single <dl>.

Example Uses

I’ve put together a couple of appropriate uses of <dl> to get your creative juices flowing.

Glossary

<dl> can be used to mark-up a glossary of terms, although you must remember to use <dfn> to indicate that the word is defined here:

<article>
  <h2>The article element</h2>
  <p>An independent piece of content, one suitable for putting in an
    article element, is content that makes sense on it’s own. This yardstick
    is up to your interpretation, but an easy smell test is would this make sense
    in an RSS feed? Of course weblog articles and static pages would make sense
    in a feed reader, and some sites have weblog comment feeds..</p>
  ...
  <aside>
    <h3>Glossary</h3>
    <dl>
      <dt><dfn>RSS</dfn></dt>
      <dd>An XML format for aggregating information from websites whose 
        content is frequently updated.</dd>
      <dt><dfn>Weblog</dfn></dt>
      <dd>Contraction of the term "web log", a weblog is a 
        website that is periodically updated, like a journal</dd>
    </dl>
  </aside>
</aticle>

The example content is from our recent post on the article element. In the example, I plucked out the terms “RSS” and “weblog” and defined them in a handy glossary. Since this information is supplementary to the article, the glossary has been placed in an <aside>.

Metadata

<dl> is also appropriate for marking up content metadata, such as information about our article on how to use HTML5 in your client work right now.

<dl>
  <dt>Authors:</dt>
  <dd>Remy Sharp</dd>
  <dd>Rich Clark</dd>
  <dt>Editor:</dt>
  <dd>Brandan Lennox</dd>
  <dt>Category:</dt>
  <dd>Comment</dd>
</dl>

Since Remy and Richard contributed to that article, they are both listed as authors, showing the pairing of multiple values (<dd>) to one key (<dt>).

Multiple keys (<dt>) to a single value

As mentioned above, a <dl> may map many keys (<dt>) to many values (<dd>). This means that one term might have multiple descriptions, or there may be multiple terms that mean the same thing. Related <dt>s should follow each other immediately before their descriptive <dd>.

<dl>
  <dt lang="en-GB"><dfn>colour</dfn></dt>
  <dt lang="en-US"><dfn>color</dfn></dt>
  <dd>The visual result of light in their emission, transmission and/or reflection. This perception is determined by the hue, brightness and saturation of the light at a specific point. </dd>
</dl>

Here I have indicated that there are two different spellings of “colour” and grouped these terms to match them with the same description.

It is not appropriate, however, to use the same key multiple times within a single <dl>. You can’t define “car” as one thing at the start of a <dl> and then define it again at the end of that same <dl>. If you have multiple descriptions for a single term, you should list both <dd>s directly under the same <dt>.

<dl>
  <dt><dfn>Chips</dfn></dt>
  <dd>Strips of potato usually deep fried in fat. Commonly referred to as "french fries".</dd>
  <dd>A small fragment that has been broken off from a larger body (e.g. stone).</dd>
</dl>

What it should not be used for

Dialogue was a suggested use for <dl> in HTML 4, which was widely debated and often considered inappropriate. This application of the element is no longer recommended in HTML5, and the new definition of the element does indeed back this up. When marking up a conversation, you’re not describing the speaker, but rather stating what they said. With the demise of <dialog>, conversations have no specific markup element. Instead, the specification makes recommendations of how to mark up conversations.

Summary

The changes to <dl> are fairly minor, but the new definition should clear up confusion and enable developers to use it more appropriately. You can use this element to represent key-value pairs semantically and couple it with other elements like <details> and <aside> to give context to this information.

Where do you see yourself using <dl> in HTML5? Perhaps details about a downloadable file? Or are you going to give your more technical blog articles a glossary? Let us know in the comments!

The dl element originally appeared on HTML5 Doctor on June 3, 2010.