HTML Guides for dt

Within a <dl>, each name should appear in only one <dt>, so a term with several values gets one <dt> followed by several <dd> elements.

A description list is a set of name-value groups, and the HTML specification says a single <dl> should not have more than one <dt> for each name. When the same term shows up twice with different values, readers can't tell whether the second entry replaces the first, adds to it, or is a mistake. Repeated terms often come from lists built from data, such as product specifications where one attribute is output twice.

The validator compares the text content of each <dt>. It ignores markup and leading or trailing whitespace, so <dt><b>Size</b></dt> and <dt> Size </dt> both count as Size. The comparison is case-sensitive, so Size and size are different names. Wrapping each group in a <div> doesn't help, because the check covers the whole <dl>. Along with this warning, the validator adds a second message pointing to the first <dt> with that name.

If both values belong to the same term, keep one <dt> and put each value in its own <dd>. If the entries describe different things that share a label, give each <dt> a distinct name, or move them into separate <dl> elements, since the rule applies only within a single list.

Invalid example

<dl>

<dt>Size</dt>

<dd>Small</dd>

<dt>Color</dt>

<dd>Red</dd>

<dt>Size</dt>

<dd>Medium</dd>

</dl>

Valid example

<dl>

<dt>Size</dt>

<dd>Small</dd>

<dd>Medium</dd>

<dt>Color</dt>

<dd>Red</dd>

</dl>

Valid example with distinct names

<dl>

<dt>Net weight</dt>

<dd>1.2 kg</dd>

<dt>Gross weight</dt>

<dd>1.4 kg</dd>

</dl>

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>

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>

This message points to the first <dt> in a <dl> whose name is repeated later in the same list.

It always comes with a duplicate dt name warning on the later <dt>. Together, the two messages show where each copy of the term is, so you can compare them and decide which one to keep. The HTML specification says a single <dl> should not have more than one <dt> for each name.

The validator compares the text content of each <dt>. It ignores markup and leading or trailing whitespace, so <dt><b>Size</b></dt> and <dt>Size</dt> have the same name. The comparison is case-sensitive, so Size and size don't clash.

The first <dt> is usually fine on its own; the fix goes where the name repeats. If both entries describe the same term, keep one <dt> and give each value its own <dd>. If they describe different things, give each <dt> a distinct name. Once every name in the list is unique, both messages go away.

Invalid example

<dl>

<dt>Size</dt>

<dd>Small</dd>

<dt>Color</dt>

<dd>Red</dd>

<dt>Size</dt>

<dd>Medium</dd>

</dl>

Valid example

<dl>

<dt>Size</dt>

<dd>Small</dd>

<dd>Medium</dd>

<dt>Color</dt>

<dd>Red</dd>

</dl>