<dl>: The Description List element #

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

Try it #

::: section-content ::: iframe ::: {.output-header .border-rounded-top}

HTML Demo: <dl> #

Reset :::

::: {#warning-no-script .warning-container} ::: warning The interactive example cannot be shown because JavaScript is disabled. ::: :::

::: {#warning-mathml-not-supported .warning-container .hidden} ::: warning The interactive example cannot be shown because MathML is not supported by your browser. ::: :::

::: {#editor-container .editor-container .tabbed-standard .hidden .border-rounded-bottom editor-type=“tabbed”} ::: {#tab-container .section .tabs} ::: {#tablist .tab-list role=“tablist”} HTML

CSS

JavaScript :::

::: {#html-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“html” aria-hidden=“true”} ::: {#html-editor}

Cryptids of Cornwall:

<dl>
  <dt>Beast of Bodmin</dt>
  <dd>A large feline inhabiting Bodmin Moor.</dd>

  <dt>Morgawr</dt>
  <dd>A sea serpent.</dd>

  <dt>Owlman</dt>
  <dd>A giant owl-like creature.</dd>
</dl>

::: :::

::: {#css-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“css” aria-hidden=“true”} ::: {#css-editor} p, dt { font-weight: bold; }

dl,
dd {
  font-size: 0.9rem;
}

dd {
  margin-bottom: 1em;
}

::: :::

::: {#js-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“js” aria-hidden=“true”} ::: {#js-editor} ::: ::: :::

::: {#output .output-container}

Output #

::: :::

::: {.section .console-container .hidden aria-hidden=“true”}

Console Output #

![] clear console

::: {#console .console} ::: :::

::: {#html-output .output .editor-tabbed} %html-content% ::: :::

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 `<dt>` elements followed by one or more `<dd>` elements, optionally intermixed with `<script>` and `<template>` elements. Or: (in WHATWG HTML, W3C HTML 5.2 and later) One or more `<div>` elements, optionally intermixed with `<script>` and `<template>` elements.
Tag omission	None, both the starting and ending tag are mandatory.
Permitted parents	Any element that accepts flow content.
Implicit ARIA role	No corresponding role
Permitted ARIA roles	`group`, `list`, `none`, `presentation`
DOM interface	`HTMLDListElement`

:::

Attributes #

::: section-content This element only includes the global attributes. :::

Examples #

Single term and description #

::: section-content ::: code-example [html]{.language-name}

<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>

:::

Result #

::: {#sect1 .code-example} ::: iframe ::: ::: :::

Multiple terms, single description #

::: section-content ::: code-example [html]{.language-name}

<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>

:::

Result #

::: {#sect2 .code-example} ::: iframe ::: ::: :::

Single term, multiple descriptions #

::: section-content ::: code-example [html]{.language-name}

<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>

:::

Result #

::: {#sect3 .code-example} ::: iframe ::: ::: :::

Multiple terms and descriptions #

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

Metadata #

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

::: code-example [html]{.language-name}

<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>

:::

Result #

::: {#sect4 .code-example} ::: iframe ::: :::

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

::: code-example [css]{.language-name}

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

::: :::

Wrapping name-value groups in `div` elements #

::: section-content WHATWG HTML allows wrapping each name-value group in a <dl>{aria-current=“page”} element in a `` element. This can be useful when using microdata, or when global attributes apply to a whole group, or for styling purposes.

::: code-example [html]{.language-name}

<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>

:::

Result #

::: {#sect5 .code-example} ::: iframe ::: ::: :::

Notes #

::: section-content Do not use this element (nor <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 margin property. :::

Accessibility concerns #

::: section-content 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{target="_blank"}
Brief Note on Description List Support{target="_blank"} :::

Specifications #

::: _table #

Specification #

HTML Standard
[# the-dl-element]{.small}

:::

Browser compatibility #

::: _table Desktop Mobile

     Chrome    Edge   Firefox   Internet Explorer   Opera   Safari   WebView Android   Chrome Android   Firefox for Android   Opera Android   Safari on IOS   Samsung Internet

dl 1 12 1 Yes 15 ≤4 4.4 18 4 14 ≤3.2 1.0 :::

<dl>: The Description List element #

Try it #

HTML Demo: <dl> #

Output #

Console Output #

Attributes #

Examples #

Single term and description #

Result #

Multiple terms, single description #

Result #

Single term, multiple descriptions #

Result #

Multiple terms and descriptions #

Metadata #

Result #

Wrapping name-value groups in div elements #

Result #

Notes #

Accessibility concerns #

Specifications #

::: _table #

Specification #

Browser compatibility #

See also #

Wrapping name-value groups in `div` elements #