Description Lists

Displaying lists of terms and their descriptions (or keys and their values), like for displaying metadata or glossaries

Overview

Description lists (<dl> HTML elements) are useful for showing structured lists of terms and their descriptions/definitions. They are more flexible and responsive than vertical tables, and they support having more than one description entry for each term.

Simple Example: Page Metadata

Page Title: Description Lists
Page Description: Displaying lists of terms and their descriptions (or keys and their values), like for displaying metadata or glossaries
Page ID: 1222962

Reference

Learn more about the description list HTML element.

CSS Classes

There are two CSS classes available, both for the parent <dl> tag.

metadata: base class (required for styling).
striped: makes every other <dt> and its corresponding <dd> have a background, which can be easier to read (optional).

Usage/Layout Notes

Description lists should have headings to denote the group of terms being described.

It is recommended that description lists go inside containers that have widths that correspond to the term + description content. This avoids either an awkward amount of space being between the term and the description, or squished and cramped description content.

In the first example above in the Overview section, the "Page Description" term's description is relatively long, so it works fine in a wide container. In the Example section below, both the terms and descriptions are relatively short so it was placed inside a 50% wide row column.

Examples

Terms With Multiple Descriptions

Here is an example with stripes and more than one <dd> description for some <dt> terms.

Name: Lisa Simpson
Age: 8
Parents: Marge Simpson; Homer Simpson
Siblings: Bart Simpson; Maggie Simpson
Hobbies: School; Music
Instrument: Saxaphone

Description List Example

<dl class="metadata striped">
    <dt>Name</dt>
    <dd>Lisa Simpson</dd>
   
    <dt>Age</dt>
    <dd>8</dd>
   
    <dt>Parents</dt>
    <dd>Marge Simpson</dd>
    <dd>Homer Simpson</dd>
   
    <dt>Siblings</dt>
    <dd>Bart Simpson</dd>
    <dd>Maggie Simpson</dd>
   
    <dt>Hobbies</dt>
    <dd>School</dd>
    <dd>Music</dd>
   
    <dt>Instrument</dt>
    <dd>Saxaphone</dd>
</dl>

Real-World Usage

Here are some places where you can see description lists being used in real situations:

My City Account and Profile (must be logged in to My City).
BPS Projects detail page (click on a project to view).

Help Us Improve This Page

Did you notice an error? Is there information that you expected to find on this page, but didn't? Let us know below, and we'll work on it.

Feedback is anonymous.

Style Guide