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

> Canonical HTML version: https://rocketvalidator.com/html-validation/the-element-h2-must-not-appear-as-a-descendant-of-the-dt-element
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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`

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

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

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

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

```html
<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.