HTML Description List: dl, dt and dd with Examples
November 11, 2026 · 10 min read
HTML Description List: How to Use dl, dt, and dd
An HTML description list pairs names with values using three tags. <dl> wraps the list, <dt> holds each term, and <dd> holds its description. Use it for glossaries, metadata blocks and question-answer pairs. Below you'll find the grouping rules, div wrappers, a side-by-side CSS layout and screen reader behaviour.
What Is an HTML Description List?
A description list is HTML's built-in structure for name-value data. The WHATWG HTML standard calls <dl> an association list made of zero or more name-value groups. Those groups can be terms and definitions, metadata topics and values, or questions and answers.
The name has changed over time. HTML 4.01 called it a definition list, which is why older tutorials and searches still say HTML definition list. Current HTML calls it a description list, since glossaries are only one use. A product spec sheet or the author and licence lines on a document page fit just as well.
Here's the smallest useful example:
<dl>
<dt>Format</dt>
<dd>Plain-text file with a .md extension</dd>
<dt>Encoding</dt>
<dd>UTF-8</dd>
</dl>
A browser shows "Format" and "Encoding" flush with the left edge. Each description sits on its own line below its term, pushed right by a 40px indent. There are no bullets, numbers or bold text unless you add them.
How Do dl, dt, and dd Fit Together?
Each group is one or more <dt> elements followed by one or more <dd> elements. A new group starts whenever a <dt> follows a <dd>. That's the whole grammar, and it explains every valid pattern in the next section.
Each element has its own content rules:
<dl>accepts only<dt>/<dd>groups or<div>wrappers, plus<script>and<template>. Both its opening and closing tags are required.<dt>accepts flow content, but no headings,<header>,<footer>or sectioning elements such as<section>. So you can't put an<h3>inside a term.<dd>accepts any flow content: paragraphs, lists, images, even a nested<dl>.
The spec does let you omit the closing tags of <dt> and <dd> when the next element is another <dt> or <dd>. Close them anyway. Explicit end tags make each group's boundaries obvious to the next person who edits the markup, and they prevent surprises when someone adds other elements later. Our guide to tags in HTML lists the other elements with optional end tags.
Two rules from the spec catch people out. Each name should appear only once in a single <dl>. And several <dd> elements in one group are alternative values, so a multi-paragraph description belongs inside one <dd> as separate <p> elements.
Can One Term Have Several Descriptions?
Yes, and the reverse works too. The grouping rule allows one-to-many, many-to-one and many-to-many groups.
One term, several descriptions. List each alternative as its own <dd>:
<dl>
<dt>Licence</dt>
<dd>MIT for the source code</dd>
<dd>CC BY 4.0 for the documentation</dd>
</dl>
Both descriptions render indented under "Licence", one per line.
Several terms, one description. Stack the <dt> elements before a single <dd>. This suits spelling variants and synonyms:
<dl>
<dt>Color</dt>
<dt>Colour</dt>
<dd>The hue, saturation and lightness of an element</dd>
</dl>
Both terms appear on separate lines, followed by the one shared description.
When the term really is being defined, as in a glossary, wrap it in <dfn>. A plain <dt> only marks a name. The dfn element tells software that this is the defining instance of the term:
<dl>
<dt><dfn>Front matter</dfn></dt>
<dd>A metadata block at the top of a file, usually written in YAML.</dd>
</dl>
Can You Put a div Inside a dl?
Yes. The current standard lets you wrap each name-value group in a <div>. The spec gives three reasons: attaching microdata, setting global attributes such as id or class on a whole group, and styling.
<dl>
<div id="release">
<dt>Release</dt>
<dd>2.4.0</dd>
</div>
<div id="released">
<dt>Released on</dt>
<dd>11 November 2026</dd>
</div>
</dl>
The wrappers don't change what the list means, and browsers render it the same way. The catch is that it's all or nothing. A <dl> holds either bare <dt>/<dd> groups or <div> wrappers, never a mix of both.
Each <div> must also hold exactly one complete group. You can't wrap two groups in one <div>, and you can't wrap a lone <dt> while leaving its <dd> outside. The W3C markup validator flags both mistakes, so run your page through it after refactoring.
Styling an HTML Description List With CSS
The browser's built-in stylesheet does very little. Per the HTML rendering rules, <dl> gets margin-block: 1em and each <dd> gets margin-inline-start: 40px. Terms aren't bold by default, and the old compact attribute is obsolete, so all spacing and weight come from CSS. Most designs begin with a small reset:
dt {
font-weight: 600;
}
dd {
margin-inline-start: 0;
margin-block-end: 0.75rem;
}
That stacks every term above its description, flush left, with a gap before the next group.
Want terms on the left and descriptions on the right? CSS grid does the job in a few lines.
dl {
display: grid;
grid-template-columns: max-content 1fr;
gap: 0.5rem 1.5rem;
}
dt {
grid-column: 1;
font-weight: 600;
}
dd {
grid-column: 2;
margin: 0;
}
Because grid's auto-placement never moves backwards, each <dt> starts a new row in column 1. A second <dd> under the same term drops to the next row in column 2. Stacked <dt> elements fill column 1 row by row, and their shared <dd> lines up beside the last of them.
Narrow screens need one more rule, or long descriptions get squeezed:
@media (max-width: 30rem) {
dl {
grid-template-columns: 1fr;
}
dt,
dd {
grid-column: 1;
}
}
If you used <div> wrappers, put the grid on each wrapper instead, with dl > div { display: grid; grid-template-columns: 10rem 1fr; }, and keep the dt and dd column rules. A fixed first column keeps the terms aligned from row to row.
How Do Screen Readers Announce a Description List?
A <dl> has no implicit ARIA role, and the MDN dl reference states that each screen reader exposes it differently. Some announce a total count, some announce terms and definitions, and navigation varies too. MDN says those differences aren't necessarily bugs.
MDN singles out VoiceOver. Since iOS 14, it announces <dl> content as a list when you move through it with the virtual cursor, but not during read-all. VoiceOver doesn't support list navigation commands for a <dl> either, so a user can't jump from list to list the way they can with <ul>.
You'll be tempted to fix this with ARIA. Be careful. Adding role="term" and role="definition" changes how VoiceOver on macOS and iOS announces the content, per MDN. The permitted roles on <dl> itself are group, list, none and presentation, and none of them makes every screen reader behave alike.
That's the honest limitation of an HTML description list: you can't force identical announcements across assistive tech. What you can do is write terms that make sense when read aloud on their own. Then the structure helps, and nothing breaks when a reader ignores it.
When to Use dl Instead of ul or a Table
Pick the element by the shape of your data, not by how you want it to look.
| Your content | Element |
|---|---|
| Names paired with values or explanations | <dl> |
| A set of items with no labels | <ul>, or <ol> when order matters |
| Records compared across several columns | <table> |
| Data people sort or scan by column | <table> |
The list tags cover different jobs. <ul> and <ol> hold <li> items, while <dl> holds <dt>/<dd> pairs. For Markdown's bullet and numbered syntax, see our Markdown lists guide. The HTML code for bullets and numbers is in our bullet point HTML guide.
A table only earns its place once you have three or more columns, or a header row people use to compare records. For two columns of label and value, we prefer <dl>. It reflows to a single column on a phone without horizontal scrolling, and screen readers don't announce it as a grid with row and column counts.
One anti-pattern to drop: don't use a <dl> or <ul> just to indent text. MDN calls it out as bad practice. Use margin-inline-start or padding-inline-start in CSS instead.
Writing dl Markup Inside Markdown Files
Core Markdown has no syntax for description lists. Some processors add a colon-based extension, and our Markdown definition list guide covers that syntax and where it works. Anywhere a Markdown file accepts raw HTML, though, a <dl> block works. Our Markdown vs HTML comparison explains when mixing the two makes sense.
Keep the whole <dl> free of blank lines, because a blank line ends an HTML block in CommonMark parsers. The definition list guide covers the other habits that keep raw HTML rendering inside Markdown.
Our editor's preview renders raw <dl> HTML, but not the Markdown colon syntax. Try it below: the list shows one term with one description, two terms sharing one, and one term with two. Click Export HTML to see the full document the Markdown to HTML converter generates.
The demo shows the markup only. Add the grid CSS from the styling section to your own site's stylesheet.
Description List Questions, Answered
An HTML description list is the right element whenever your content comes in name-value pairs. Keep each group as one or more <dt> followed by one or more <dd>. Wrap groups in a <div> only when you need to, and lay them out with a short grid rule. Paste a <dl> block into the editor to check the markup renders before you add it to your site.