HTML Guides for description list

A dt element can't contain a heading, from h1 to h6, at any depth. Move the heading before the description list or into a dd, or style the term with CSS.

The dt element holds a term or name in a description list (dl). The HTML standard lets it contain flow content, such as text, strong, span or a p, with a few exceptions: no heading content (h1 to h6 and hgroup), no sectioning content (article, aside, nav, section), and no header or footer anywhere inside it. The rule applies at any depth, so a heading wrapped in a div inside the dt still triggers this error. The message names the heading level the validator found, and the fix is the same for every level.

A dt names a term, while headings build the outline of the page. Screen reader users who move through a page by headings land on each heading inside the list as if it started a new section, which breaks the outline the rest of the page sets up.

This often shows up in FAQ or accordion layouts, where each question sits in a small heading such as an h5 or h6 to make it bold, or when a term should simply look like a heading. The size and weight can come from CSS instead.

How to fix it

1. Move the heading before the description list. If the heading introduces a group of terms, place it above the dl element.
2. Put the heading inside a dd element. A dd accepts flow content, headings included.
3. Style the dt with CSS. If you only need the term to look like a heading, give the dt the font size and weight you want without wrapping its content in a heading element.
4. Drop the description list. If each term really should be a heading, for example so visitors can jump from one FAQ question to the next, write each one as a heading followed by its answer, at a level that fits the page's outline.

Examples

❌ Invalid: heading inside a dt

<dl>

<dt>

<h2>API Reference</h2>

</dt>

<dd>Documentation for the public API.</dd>

</dl>

The h2 is a descendant of dt, which the dt content model doesn't allow.

✅ Valid: heading placed before the description list

<h2>API Reference</h2>

<dl>

<dt>Endpoint</dt>

<dd>The URL used to access the API.</dd>

</dl>

✅ Valid: heading inside a dd element

<dl>

<dt>API Reference</dt>

<dd>

<h2>Overview</h2>

<p>Documentation for the public API.</p>

</dd>

</dl>

✅ Valid: styling the dt to look like a heading

<dl class="faq">

<dt>How long does shipping take?</dt>

<dd>Orders arrive within five working days.</dd>

</dl>

.faq dt {

font-size: 1.25em;

font-weight: bold;

}

A styled dt doesn't appear in the page's heading outline, so use it only when the term doesn't need to be a real heading.

✅ Valid: questions as headings instead of a description list

<h2>Frequently asked questions</h2>

<h3>How long does shipping take?</h3>

<p>Orders arrive within five working days.</p>