The element “h2” must not appear as a descendant of the “dt” element.

The dt element represents a term or name in a description list (dl). According to the HTML specification, its content model is restricted to phrasing content, which means it can only contain text-level elements. Heading elements (h1 through h6) are flow content, not phrasing content, so nesting them inside a dt is invalid HTML.

This restriction exists because dt is designed to label or name something, while headings define the structural outline of a document. Mixing the two creates conflicting semantics — screen readers and other assistive technologies may misinterpret the document’s heading hierarchy, leading to a confusing experience for users navigating by headings. Browsers may also handle the invalid nesting inconsistently, potentially breaking the layout or the logical structure of the description list.

This issue commonly arises when developers want to visually style a definition term as a heading. The correct approach is to either restructure the markup so the heading sits outside the dt, or to style the dt directly with CSS to achieve the desired visual appearance without misusing heading elements.

How to fix it

You have several options:

1. Move the heading before the description list. If the heading introduces a group of terms, place it above the dl element.
2. Place the heading inside a dd element instead. The dd element accepts flow content, so headings are valid there.
3. Style the dt with CSS. If you only need the term to look like a heading, apply font size, weight, and other styles directly to the dt without wrapping its content in a heading element.

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 violates the content model.

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

When the heading introduces the entire list, placing it before the dl is the cleanest solution.

✅ Valid: heading inside a dd element

<dl>
  <dt>API Reference</dt>
  <dd>
    <h2>Overview</h2>
    <p>Documentation for the public API.</p>
  </dd>
</dl>

The dd element accepts flow content, so headings are permitted there.

✅ Valid: styling the dt to look like a heading

<style>
  .term-heading {
    font-size: 1.5em;
    font-weight: bold;
  }
</style>

<dl>
  <dt class="term-heading">API Reference</dt>
  <dd>Documentation for the public API.</dd>
</dl>

This approach gives you the visual appearance of a heading while keeping the markup valid. Keep in mind that styled dt elements won’t appear in the document’s heading outline, so only use this when a true heading isn’t semantically needed.

✅ Valid: using a span for inline styling inside dt

<dl>
  <dt><span class="term-heading">API Reference</span></dt>
  <dd>Documentation for the public API.</dd>
</dl>

Since span is phrasing content, it’s perfectly valid inside dt and gives you a styling hook without breaking the content model.

Learn more:

MDN Reference

MDN Web Docs: <dt>: The Description Term element

→

MDN Reference

MDN Web Docs: The HTML Section Heading elements

→