1. <dl> has no corresponding (viz. implicit) role, but can be given the role group, list, none or presentation <https://w3c.github.io/html-aria/#el-dl>.
Wow I have never noticed that, thanks for the heads up! Out of curiosity, would you put `role="listitem"` on `<div>` elements that wrap the `<dt>` && `<dd>` elements? It looks like `role="listitem"` is allowed on the `<dt>` element, but that doesn't feel like it would be accurate in the case where multiple `<dt>` elements are grouped together, and I'm not sure if that would mess with how the element is interpreted natively as as term.
List history (listory?) lesson, kids: As the link below to a 1985 IBM mainframe DCF/GML manual shows, DL-DT-DD have been a thing since before the web. In addition to Definition lists (DL), the 40+ year-old documentation describes Glossary lists (GL), Ordered lists (OL), Unordered lists (UL), and Simple lists (SL).
ibm :: 370 :: DCF :: SH35-0050-2 Document Composition Facility Generalized Markup Language Implementation Guide Rel 3 Mar85
This is going to be unpopular here, but life became easier when I quit trying to write semantic HTML. It’s just poorly designed, I’m sorry. Every time I’ve reached for a <dl> I’ve eventually regretted it because I wanted multiple levels of wrappers, or a divider between sections, or an icon, or a heading spanning multiple key-value pairs, etc. They make this stuff with some flexibility but nowhere near enough to actually cover the generalized concept it purports to. I still use the corresponding elements when there are observable benefits, of course, like <button>, <h1>, etc, but when all it’s going to do is not quite fit the data model and force me to override everything, it’s just not a practical choice.
It shouldn’t be so controversial to say that if 99% of usage routes around your API, it’s probably the API’s fault.
Sounds like it's CSS' fault then. I think that just like they introduced `display:contents` to remove wrappers, they should also introduce a way to group elements as if they had a common ancestor.
As a person who daily drives a screen reader, I so agree with this.
We'd all be better off if the W3 dispensed with all that ideological semantic purity BS and started doing more realpolitik. Think not about whether your API is semantically pure, but about what developers want to do, what hacks they'll use to achieve their goals despite your objections, and how to enable doing those things in a way that is maximally beneficial to everyone involved.
ARIA live regions are the perfect example. What developers actually want is `document.speakText`. What developers actually have is a weird API that announces text on the page as it changes. They have to bridge from one to the other, which is difficult and hacky, even when implemented well. But hey, at least that live region approach is semantically pure HTML...
> Prior to HTML5, this was called a definition list. This is because the <dl> was originally only intended to represent glossaries of terms and their definitions.
I've been following roadmap.sh, and while it's not a comprehensive learning resource, it does help close obvious knowledge gaps. As it happens I was just reading about this.
I love DL. I think tables, at least in the past, were misused as DLs even more in the past and the inconvenience of the table markup is even worse than a bunch of divs.
As others have noted only the div is allowed. This isn't a unique situation either, the HTML spec despite being lenient in syntax is quite restrictive in behavior. It's unfortunate that XHTML (and XML parsing) didn't become the default as it's the opposite, more restrictive syntax, but lenient behavior.
For example in XHTML you can use custom elements as table rows or cells (provided you give them the correct role and CSS display property). This is because XHTML does not modify the tree during parsing, unlike HTML which will hoist out custom element children of the table to the table's parent.
I've used this a good amount of times, when I coded in front end projects. The first time gave me that satisfying feeling of using the right tool for the job, like completing a puzzle of HTML semantics. I remember JAWS not announcing it correctly in 2018, not sure if it's better now.
When I checked in 2024 or 2025, Windows Narrator announced it differently in Chrome, Firefox, Edge (Chromium mode) and Edge (IE mode), and none of them worked how I would expect them to. Adrian Roselli's verdict (https://adrianroselli.com/2025/01/updated-brief-note-on-desc...):
> Description list support continues to be generally good (with VoiceOver still the outlier), even if you may not like how it is supported.
You shouldn't try to fix this kind of thing by mangling the HTML, since (1) users tend to be used to their screen reader's quirks, and (2) in situations like these, making it juuuust right in one screen reader is likely to make it incomprehensible in another. But it is important to be aware of these quirks, so you don't accidentally design an interface that relies on less-quirky behaviour.
> Admittedly, however, support for the <dl> element is not yet universal.
Wait what? <DL> has been in HTML since.. the first draft in 1993!
I like DL's but they can be challenging to style. This article is using a lot of fixed pixel widths which would break on really small screens or larger data.
Well, it took about a decade for web standards to become a real thing and a lot longer for Web Platform Tests to come to be. Still, while there are lots of tests for DOM construction and visual rendering, testing construction of the accessibility tree is lacking (also keyboard interaction testing).
And that's just for browsers, there's no shared spec for the operating system accessibility APIs the browsers' accessibility tree has to be translated into or how screen readers (and other assistive technologies) will use the OS's APIs.
I was a bit surprised to see nested <div>s given as some sort of precursor pattern, when <dl> was part of HTML before 2.0 back in the days of table layout.
I need to learn more about web accessibility, but if you completely ignore it (and other sane practices) HTML looks really simple.
I think the design of HTML is just too much. There’s so many tags that don’t do much. It’s like w3c decided that any common thing people use in websites needs a tag. The end result is more and more tags…
Can anyone convince me otherwise? It screams design red-flags to me.
PS: I love the web and think it’s the best platform and future platform we have at the moment. It’s just quirky and loves not breaking old websites!
That very simply puts terms side-by-side data in a nice obvious way. (Even with multiple DDs per DT.) A bit like the Wikipedia screenshot in the article but that's more balanced `grid-template-columns: 1fr 1fr;`. (But that's the flexibility of CSS Grid, right? Real easy to tweak this further for your needs/interests/design.)
We've always used this in our ebooks for abbreviation and glossary lists. The problem I've always had is that you need to use a bit of css to make two lined-up columns. I've done it with floats. Now, some ebook readers will support grid and flex-box, which give better results, but the Kindle still does not. Kindle is sort of the IE6 of the ebook world.
It always bugs me that the naming of the element does not seem to really fit examples like „Author: Tolkien“. It‘s not that _Tolkien“_ „defines“ the „term“ _Author_ right? The elements are still used for key-value-lists and no one seems to notice or comment on this issue.
As the article points out, HTML5 softened the name from "definition list" to "description list" to move it a bit away from thinking of it as a "dictionary" definition and somewhat better reflect how it has always been used.
> <dl aria-label="Ability Scores">
This is incorrect:
1. <dl> has no corresponding (viz. implicit) role, but can be given the role group, list, none or presentation <https://w3c.github.io/html-aria/#el-dl>.
2. You’re only allowed to define aria-label on elements that have a compatible role, implicit or explicit <https://w3c.github.io/html-aria/#docconformance-naming>.
3. aria-label is allowed on all but a handful of roles <https://www.w3.org/TR/wai-aria-1.2/#aria-label>, which in this case knocks out presentation and none, leaving group and list.
4. group doesn’t feel right, list feels acceptable.
In summary: either ditch the aria-label, or add role="list" (meaning also role="listitem" on children).
—⁂—
One thing the article misses is that you can have multiple <dt> in a row too, not just <dd>. The spec has a good example: https://html.spec.whatwg.org/multipage/grouping-content.html...
They’re not name–value pairs, they’re name–value groups.
Wow I have never noticed that, thanks for the heads up! Out of curiosity, would you put `role="listitem"` on `<div>` elements that wrap the `<dt>` && `<dd>` elements? It looks like `role="listitem"` is allowed on the `<dt>` element, but that doesn't feel like it would be accurate in the case where multiple `<dt>` elements are grouped together, and I'm not sure if that would mess with how the element is interpreted natively as as term.
Your comment put me on a side quest to research the differences between i.e., e.g., viz. and sc. and I have to admit that I’m still not 100% sure
List history (listory?) lesson, kids: As the link below to a 1985 IBM mainframe DCF/GML manual shows, DL-DT-DD have been a thing since before the web. In addition to Definition lists (DL), the 40+ year-old documentation describes Glossary lists (GL), Ordered lists (OL), Unordered lists (UL), and Simple lists (SL).
ibm :: 370 :: DCF :: SH35-0050-2 Document Composition Facility Generalized Markup Language Implementation Guide Rel 3 Mar85
https://archive.org/details/bitsavers_ibm370DCFSpositionFaci...
This is going to be unpopular here, but life became easier when I quit trying to write semantic HTML. It’s just poorly designed, I’m sorry. Every time I’ve reached for a <dl> I’ve eventually regretted it because I wanted multiple levels of wrappers, or a divider between sections, or an icon, or a heading spanning multiple key-value pairs, etc. They make this stuff with some flexibility but nowhere near enough to actually cover the generalized concept it purports to. I still use the corresponding elements when there are observable benefits, of course, like <button>, <h1>, etc, but when all it’s going to do is not quite fit the data model and force me to override everything, it’s just not a practical choice.
It shouldn’t be so controversial to say that if 99% of usage routes around your API, it’s probably the API’s fault.
Sounds like it's CSS' fault then. I think that just like they introduced `display:contents` to remove wrappers, they should also introduce a way to group elements as if they had a common ancestor.
As a person who daily drives a screen reader, I so agree with this.
We'd all be better off if the W3 dispensed with all that ideological semantic purity BS and started doing more realpolitik. Think not about whether your API is semantically pure, but about what developers want to do, what hacks they'll use to achieve their goals despite your objections, and how to enable doing those things in a way that is maximally beneficial to everyone involved.
ARIA live regions are the perfect example. What developers actually want is `document.speakText`. What developers actually have is a weird API that announces text on the page as it changes. They have to bridge from one to the other, which is difficult and hacky, even when implemented well. But hey, at least that live region approach is semantically pure HTML...
The world's first website makes heavy use of <dl>s.
https://info.cern.ch/hypertext/WWW/TheProject.html
https://info.cern.ch/ (A landing page of sorts to give context and orientation about the actual first website.)
> Prior to HTML5, this was called a definition list. This is because the <dl> was originally only intended to represent glossaries of terms and their definitions.
TIL I’ve been naming it wrong for a decade.
Bleh. <b> is apparently now bring attention to. As if.
You’re not alone. This is the second time this week I’ve seen that, and thought it was a mistake the first time.
I don’t want to check what year html5 was standardized because I think it may be north of a decade ;)
TIL The name was changed from a definition list.
Here's a useful note on how well screen readers support DL: https://adrianroselli.com/2025/01/updated-brief-note-on-desc...
I've been following roadmap.sh, and while it's not a comprehensive learning resource, it does help close obvious knowledge gaps. As it happens I was just reading about this.
https://roadmap.sh/html (see "Definition lists")
The final example of the DnD statt sheet makes me think whether it's legal to nest <dl>s?
I.e. can we do
Yes. Any flow content is permitted inside a <dd>. See:
https://html.spec.whatwg.org/#the-dd-element
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
I love DL. I think tables, at least in the past, were misused as DLs even more in the past and the inconvenience of the table markup is even worse than a bunch of divs.
It's not that inconvenient if you omit unnecessary closing tags:
I find it simpler and cleaner than any of the markdown table markupsYou're right, but forcing tables to cosplay as DLs was far from the worst way that tables were abused.
I always thought the DL as a single row of a table.
I'm curious if the spec actually says you can only wrap it with a div because I like to do semantic html and name my elements specific to my domain.
As others have noted only the div is allowed. This isn't a unique situation either, the HTML spec despite being lenient in syntax is quite restrictive in behavior. It's unfortunate that XHTML (and XML parsing) didn't become the default as it's the opposite, more restrictive syntax, but lenient behavior.
For example in XHTML you can use custom elements as table rows or cells (provided you give them the correct role and CSS display property). This is because XHTML does not modify the tree during parsing, unlike HTML which will hoist out custom element children of the table to the table's parent.
Yep, I was a little surprised about that too, seem like it is valid though https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
Seems like div is the only recommended wrapper element:
https://html.spec.whatwg.org/multipage/grouping-content.html...
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
EDIT everyone replied at once lol. I'm surprised too about div.
Also, screen reader support: https://a11ysupport.io/tech/html/dl_element
Yes: https://html.spec.whatwg.org/multipage/grouping-content.html...
Custom-named elements are divs.
I've used this a good amount of times, when I coded in front end projects. The first time gave me that satisfying feeling of using the right tool for the job, like completing a puzzle of HTML semantics. I remember JAWS not announcing it correctly in 2018, not sure if it's better now.
When I checked in 2024 or 2025, Windows Narrator announced it differently in Chrome, Firefox, Edge (Chromium mode) and Edge (IE mode), and none of them worked how I would expect them to. Adrian Roselli's verdict (https://adrianroselli.com/2025/01/updated-brief-note-on-desc...):
> Description list support continues to be generally good (with VoiceOver still the outlier), even if you may not like how it is supported.
You shouldn't try to fix this kind of thing by mangling the HTML, since (1) users tend to be used to their screen reader's quirks, and (2) in situations like these, making it juuuust right in one screen reader is likely to make it incomprehensible in another. But it is important to be aware of these quirks, so you don't accidentally design an interface that relies on less-quirky behaviour.
> Admittedly, however, support for the <dl> element is not yet universal.
Wait what? <DL> has been in HTML since.. the first draft in 1993!
I like DL's but they can be challenging to style. This article is using a lot of fixed pixel widths which would break on really small screens or larger data.
Well, it took about a decade for web standards to become a real thing and a lot longer for Web Platform Tests to come to be. Still, while there are lots of tests for DOM construction and visual rendering, testing construction of the accessibility tree is lacking (also keyboard interaction testing).
And that's just for browsers, there's no shared spec for the operating system accessibility APIs the browsers' accessibility tree has to be translated into or how screen readers (and other assistive technologies) will use the OS's APIs.
Granted, I do not know what I am doing with CSS, but the Character Sheet example seems standard flexible elements?
Some of the extracted CSS chunks
I've found CSS Grid is extremely useful for styling DLs.
I was a bit surprised to see nested <div>s given as some sort of precursor pattern, when <dl> was part of HTML before 2.0 back in the days of table layout.
It’s probably aimed at React developers, many of which are probably not even aware that elements other than <div> exist.
The <dl> tag seems to cover a subset of a broad semantic space, but doesn’t easily extend beyond adding another <dd>.
I dunno, I guess I’m a caveman. If it looks right and works (including accessibility) then I figure I’m pursuing something that doesn’t matter a lot.
Shameless plug: you might be interested in https://calvinlc.com/p/2026/02/11/everything-is-a-div.html
I need to learn more about web accessibility, but if you completely ignore it (and other sane practices) HTML looks really simple.
I think the design of HTML is just too much. There’s so many tags that don’t do much. It’s like w3c decided that any common thing people use in websites needs a tag. The end result is more and more tags…
Can anyone convince me otherwise? It screams design red-flags to me.
PS: I love the web and think it’s the best platform and future platform we have at the moment. It’s just quirky and loves not breaking old websites!
Hoped to see CSS for the alternative, where <div> is not nested inside the <dl>. Too used to thinking of div as "layout containers."
CSS Grid is a very good friend when trying to style DL without extra DIV wrappers. An example:
That very simply puts terms side-by-side data in a nice obvious way. (Even with multiple DDs per DT.) A bit like the Wikipedia screenshot in the article but that's more balanced `grid-template-columns: 1fr 1fr;`. (But that's the flexibility of CSS Grid, right? Real easy to tweak this further for your needs/interests/design.)The GOV.UK Design System summary list component is a description list https://design-system.service.gov.uk/components/summary-list...
And... it also uses the wrapper div for styling
The wrapper div is making me a bit sad. These days, using grid layout, you don’t actually need it in most cases
I loved the character sheet example! Fun!
We've always used this in our ebooks for abbreviation and glossary lists. The problem I've always had is that you need to use a bit of css to make two lined-up columns. I've done it with floats. Now, some ebook readers will support grid and flex-box, which give better results, but the Kindle still does not. Kindle is sort of the IE6 of the ebook world.
What about multiple '<dt>' for one or more '<dd>'?
This seems a clear enough win for things that would fit into a simple python dictionary.
Why is it preferred over <table> for laying out columns via a the character attributes at the bottom of TFA?
it's on archive html5 .flac 16-bit 44.1kHz no <dl> flag.
blog looks beautiful. I really wish I had this kind of talent for frontend.
It always bugs me that the naming of the element does not seem to really fit examples like „Author: Tolkien“. It‘s not that _Tolkien“_ „defines“ the „term“ _Author_ right? The elements are still used for key-value-lists and no one seems to notice or comment on this issue.
Am I the only one?
As the article points out, HTML5 softened the name from "definition list" to "description list" to move it a bit away from thinking of it as a "dictionary" definition and somewhat better reflect how it has always been used.
Good title