This page is In Progress

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

dl – description list

dl

For technical reasons, the title of this article is not the text used to call this API. Instead, use dl

Summary

The dl element is used to define a description list. The element encloses one or more description terms, enclosed in dt elements, and description definitions (definitions of the terms), enclosed within dd elements.

Overview Table

DOM Interface
HTMLDListElement
Permitted contents One of the following:
  • Either: Zero or more groups each consisting of one or more dt elements followed by one or more dd elements.
  • Or: A template element.
  • Or: A template element or a dt element, followed by zero or more template, dt, and dd elements, followed by a template element or a dd element.
Permitted parents Any element that can contain [flow content](/w/index.php?title=html/concepts/flowContent&action=edit&redlink=1).
Tag omission A **dl** element must have both a start tag and an end tag.
The **dl** element is often useful to create a semantic list of terms and their definitions, whether these are name value pairs, glossary terms and definitions, or anything other items that fit this pattern. **Description lists** allow you to do this easily inside HTML.

A description list is always wrapped by a single dl element. Inside that element you can place any number of child description topics, inside dt elements, and description definitions — the description or definition of the specified terms or topics — inside dd elements.

It doesn’t make sense to have an item without a description, or the other way round, but note that it is acceptable to have a single item with multiple descriptions, or a description with multiple items (see code examples section.)

The topics should always be placed before the descriptions.

A description list is not used as commonly as other types of list, except in journals, research papers, and other documentation where item/value pairs need to be displayed. For other uses, they are often not used as they are considered more difficult to style than other list types.

Examples

This example shows a simple definition list with two item/description pairs.

<dl>
  <dt>Coffee</dt>
  <dd>A popular hot drink.</dd>
  <dt>Coca Cola</dt>
  <dd>One of the leading brands of a popular cold fizzy drink.</dd>
</dl>

View live example

This example shows a definition list with a single item but multiple descriptions for that item.

<dl>
  <dt>Coffee</dt>
  <dd>A popular hot drink.</dd>
  <dd>A mid brown colour</dd>
  <dd>A common social invitation</dd>
</dl>

View live example

This example shows a definition list with a single description and multiple items fitting that description.

<dl>
  <dt>Coffee</dt>
  <dt>Tea</dt>
  <dt>Vimto (in the North of England)</dt>
  <dd>A popular hot drink.</dd>
</dl>

View live example

Typical browser default CSS properties for the dl element.

display: block;
margin-top: 16px;
margin-bottom: 16px;

Related specifications

HTML 5.1
W3C Working Draft
HTML 5
W3C Recommendation
HTML 4.01
W3C Recommendation

See also

Other articles

External resources