HTML Guides for dt

The <dl> element represents a description list — a collection of terms (<dt>) paired with their descriptions (<dd>). According to the HTML specification, the permitted content of a <dl> is either groups of <dt> and <dd> elements directly, or <div> elements that wrap those groups. This <div> wrapping option exists specifically to help with styling, since it lets you apply CSS to a term-description pair as a unit.

However, these wrapper <div> elements are not general-purpose containers inside <dl>. The spec requires that each <div> inside a <dl> contains at least one <dt> or <dd> child. A <div> that is empty, or that contains other elements like <span>, <p>, or another <div>, violates this rule and produces a validation error.

This matters for several reasons. Screen readers and assistive technologies rely on the semantic structure of description lists to convey the relationship between terms and definitions. An empty or improperly structured <div> inside a <dl> breaks that semantic contract, potentially confusing both assistive technology and browsers. Keeping your markup valid also ensures consistent rendering across all browsers.

How to Fix It

1. Ensure every <div> inside a <dl> contains at least one <dt> or <dd> — don’t leave wrapper <div> elements empty.
2. Don’t put non-<dt>/<dd> content directly inside these <div> wrappers — elements like <span>, <p>, or nested <div> elements should be placed inside a <dt> or <dd>, not as siblings to them.
3. Remove unnecessary <div> wrappers — if a <div> inside a <dl> serves no styling or grouping purpose, remove it entirely.

Examples

❌ Empty <div> inside a <dl>

<dl>
  <div>
  </div>
  <div>
    <dt>HTML</dt>
    <dd>A markup language for structuring web content.</dd>
  </div>
</dl>

The first <div> is empty and has no <dt> or <dd> child, triggering the error.

❌ <div> with only non-<dt>/<dd> children

<dl>
  <div>
    <p>This is a description list:</p>
  </div>
  <div>
    <dt>CSS</dt>
    <dd>A style sheet language for describing presentation.</dd>
  </div>
</dl>

The first <div> contains a <p> element but no <dt> or <dd>, which is invalid.

✅ Each <div> contains <dt> and <dd> elements

<dl>
  <div>
    <dt>HTML</dt>
    <dd>A markup language for structuring web content.</dd>
  </div>
  <div>
    <dt>CSS</dt>
    <dd>A style sheet language for describing presentation.</dd>
  </div>
</dl>

✅ Using <dl> without <div> wrappers

If you don’t need <div> elements for styling, you can place <dt> and <dd> directly inside the <dl>:

<dl>
  <dt>HTML</dt>
  <dd>A markup language for structuring web content.</dd>
  <dt>CSS</dt>
  <dd>A style sheet language for describing presentation.</dd>
</dl>

✅ A <dt> with multiple <dd> descriptions in a <div>

A single term can have multiple descriptions. The <div> is valid as long as it contains at least one <dt> or <dd>:

<dl>
  <div>
    <dt>JavaScript</dt>
    <dd>A programming language for the web.</dd>
    <dd>Supports event-driven and functional programming.</dd>
  </div>
</dl>

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.