index.md

---

title: '<dl>: The Description List element'
slug: Web/HTML/Element/dl
page-type: html-element
browser-compat: html.elements.dl

---

{{HTMLSidebar}}

The <dl> HTML element represents a description list. The element encloses a list of groups of terms (specified using the {{HTMLElement("dt")}} element) and descriptions (provided by {{HTMLElement("dd")}} elements). Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).

{{EmbedInteractiveExample("pages/tabbed/dl.html", "tabbed-standard")}}

Content categories	Flow content, and if the <dl> element's children include one name-value group, palpable content.
Permitted content	Either: Zero or more groups each consisting of one or more {{HTMLElement("dt")}} elements followed by one or more {{HTMLElement("dd")}} elements, optionally intermixed with {{HTMLElement("script")}} and {{HTMLElement("template")}} elements. Or: (in {{Glossary("WHATWG")}} HTML, {{Glossary("W3C")}} HTML 5.2 and later) One or more {{HTMLElement("div")}} elements, optionally intermixed with {{HTMLElement("script")}} and {{HTMLElement("template")}} elements.
Tag omission	{{no_tag_omission}}
Permitted parents	Any element that accepts flow content.
Implicit ARIA role	No corresponding role
Permitted ARIA roles	group, list, none, presentation
DOM interface	{{domxref("HTMLDListElement")}}

Attributes

This element only includes the global attributes.

Examples

Single term and description

<dl>
  <dt>Firefox</dt>
  <dd>
    A free, open source, cross-platform, graphical web browser developed by the
    Mozilla Corporation and hundreds of volunteers.
  </dd>

  <!-- Other terms and descriptions -->
</dl>

{{EmbedLiveSample("Single_term_and_description")}}

Multiple terms, single description

<dl>
  <dt>Firefox</dt>
  <dt>Mozilla Firefox</dt>
  <dt>Fx</dt>
  <dd>
    A free, open source, cross-platform, graphical web browser developed by the
    Mozilla Corporation and hundreds of volunteers.
  </dd>

  <!-- Other terms and descriptions -->
</dl>

{{EmbedLiveSample("Multiple_terms_single_description")}}

Single term, multiple descriptions

<dl>
  <dt>Firefox</dt>
  <dd>
    A free, open source, cross-platform, graphical web browser developed by the
    Mozilla Corporation and hundreds of volunteers.
  </dd>
  <dd>
    The Red Panda also known as the Lesser Panda, Wah, Bear Cat or Firefox, is a
    mostly herbivorous mammal, slightly larger than a domestic cat (60 cm long).
  </dd>

  <!-- Other terms and descriptions -->
</dl>

{{EmbedLiveSample("Single_term_multiple_descriptions")}}

Multiple terms and descriptions

It is also possible to define multiple terms with multiple corresponding descriptions, by combining the examples above.

Metadata

Description lists are useful for displaying metadata as a list of key-value pairs.

<dl>
  <dt>Name</dt>
  <dd>Godzilla</dd>
  <dt>Born</dt>
  <dd>1952</dd>
  <dt>Birthplace</dt>
  <dd>Japan</dd>
  <dt>Color</dt>
  <dd>Green</dd>
</dl>

Tip: It can be handy to define a key-value separator in the CSS, such as:

dt::after {
  content: ": ";
}

Wrapping name-value groups in div elements

WHATWG HTML allows wrapping each name-value group in a {{HTMLElement("dl")}} element in a {{HTMLElement("div")}} element. This can be useful when using microdata, or when global attributes apply to a whole group, or for styling purposes.

<dl>
  <div>
    <dt>Name</dt>
    <dd>Godzilla</dd>
  </div>
  <div>
    <dt>Born</dt>
    <dd>1952</dd>
  </div>
  <div>
    <dt>Birthplace</dt>
    <dd>Japan</dd>
  </div>
  <div>
    <dt>Color</dt>
    <dd>Green</dd>
  </div>
</dl>

Notes

Do not use this element (nor {{HTMLElement("ul")}} elements) to merely create indentation on a page. Although it works, this is a bad practice and obscures the meaning of description lists.

To change the indentation of a description term, use the CSS {{cssxref("margin")}} property.

Accessibility concerns

Each screen reader exposes <dl> content differently, including total count, terms/definitions context, and navigation methods. These differences are not necessarily bugs. As of iOS 14, VoiceOver will announce that <dl> content is a list when navigating with the virtual cursor (not via the read-all command). VoiceOver does not support list navigation commands with <dl>. Be careful applying ARIA term and definition roles to <dl> constructs as VoiceOver (macOS and iOS) will adjust how they are announced.

• VoiceOver on iOS 14 Supports Description Lists

• Brief Note on Description List Support

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}

See also

• {{HTMLElement("dt")}}

• {{HTMLElement("dd")}}