It’s used to represent a list of name–value pairs. This is a common UI pattern that, at the same time, is incredibly versatile. For instance, you’ve probably seen these layouts out in the wild…
Each of these examples shows a list (or lists!) of name–value pairs. You might have also seen lists of name–value pairs to describe lodging amenities, or to list out individual charges in your monthly rent, or in glossaries of technical terms. Each of these is a candidate to be represented with the
element.
So what does that look like?
The Anatomy of a Description List
I’ve been saying “
,” when really, I’m talking about three separate elements:
,
, and
.
We start with our
. This is the description list,[note 1] akin to using a
for an unordered list or an
for an ordered list.
Fancy.
Next up, we want to add a name–value pair. We’ll use a
, short for description term, for the name, and we’ll use a
, short for description detail, for the value.[note 2]
Title
Designing with Web Standards
Title
Designing with Web Standards
To add another name–value pair to our list, we add another
and
:
Title
Designing with Web Standards
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
But wait — what if I have a term that has multiple values? For instance, what if this book has multiple authors?
It’s used to represent a list of name–value pairs. This is a common UI pattern that, at the same time, is incredibly versatile. For instance, you’ve probably seen these layouts out in the wild…
Each of these examples shows a list (or lists!) of name–value pairs. You might have also seen lists of name–value pairs to describe lodging amenities, or to list out individual charges in your monthly rent, or in glossaries of technical terms. Each of these is a candidate to be represented with the
element.
So what does that look like?
The Anatomy of a Description List
I’ve been saying “
,” when really, I’m talking about three separate elements:
,
, and
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
There’s one last piece of the description list anatomy to look at for most basic use cases: what if I want to wrap a
and its
(s) for styling reasons?
In this case, the specs allow you to wrap a
and its
(s) in a
:
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
A wrapper
like this is the only element that can wrap those
/
groups.
And that’s it! That’s the anatomy of the description list, HTML's semantic way to mark up a list of name–value groups!
Why Do We Need Semantics For This Anyways?
Before we learned about the
,
, and
elements, my team used to use nested
s for this pattern all the time. It looked a lot like:
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
This has all the information about the book, right? Why do we need semantics for a list of name–value groups in the first place if something like a series of nested
s could get the job done?
When determining whether a semantic element might be appropriate for a given pattern, I find it helpful to ask, “What benefits — even theoretical — could we get if computers could recognize this pattern?” In this case, what lift could we get if browsers could somehow recognize a list of name–value groups?
Answers to that question will be varied. I tend to spend a lot of time advocating for web accessibility, so my first thought tends to be how screenreaders could interpret the pattern. Off the top of my head, I can think of a couple of benefits screenreader users could get from their screenreaders recognizing this pattern:
The screenreader could tell the user how many name–value groups are in the list.
The screenreader could tell the user how far into the list they are.
The screenreader could treat the list as one block that the user could skip over if they’re uninterested in it.
All of these could make the list more usable than a series of nested
s, which would treat each name and value in the list as nothing more than a standalone text node.
If you can come up with a couple of even theoretical lifts from the user’s device recognizing a pattern, then there’s a good chance that the pattern is a strong candidate for having some associated semantics.
For what it’s worth, these screenreader experiences aren’t hypothetical — they’re benefits that screenreader users really get from using
in most browser/screenreader combinations. Admittedly, however, support for the
element is not yet universal. You may decide that screenreaders’ fallback experience — treating the list as standalone text nodes — isn’t sufficient for your use case, and instead opt for something like a
until support improves.
Okay, Okay, One Last Example!
My favorite example, the one that really takes the cake for me, is Dungeons & Dragons statblocks, which are really “Oops! All Name–Value Pairs!”
No, really: just how many candidates for
s do you see in this statblock alone?
I counted five possible description lists, personally. Here’s how I chose to mark this up:
Kobold
Small humanoid (kobold), lawful evil
Armor Class
12
Hit Points
5 (2d6 - 2)
Speed
30 ft.
STR
7 (-2)
DEX
15 (+2)
CON
9 (-1)
INT
8 (-1)
WIS
7 (-2)
CHA
8 (–1)
Senses
Darkvision 60 ft.
Passive Perception 8
Languages
Common
Draconic
Challenge
1/8 (25 XP)
Sunlight Sensitivity
While in sunlight, the kobold has disadvantage on attack rolls, as well as on Wisdom (Perception) checks that rely on sight.
Pack Tactics
The kobold has advantage on an attack roll against a creature if at least one of the kobold's allies is within 5 ft. of the creature and the ally isn't incapacitated.
Actions
Dagger
Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: (1d4 + 2) piercing damage.
Sling
Ranged Weapon Attack: +4 to hit, reach 30/120 ft., one target. Hit: (1d4 + 2) bludgeoning damage.
Kobold
Small humanoid (kobold), lawful evil
Armor Class
12
Hit Points
5 (2d6 - 2)
Speed
30 ft.
STR
7 (-2)
DEX
15 (+2)
CON
9 (-1)
INT
8 (-1)
WIS
7 (-2)
CHA
8 (–1)
Senses
Darkvision 60 ft.
Passive Perception 8
Languages
Common
Draconic
Challenge
1/8 (25 XP)
Sunlight Sensitivity
While in sunlight, the kobold has disadvantage on attack rolls, as well as on Wisdom (Perception) checks that rely on sight.
Pack Tactics
The kobold has advantage on an attack roll against a creature if at least one of the kobold's allies is within 5 ft. of the creature and the ally isn't incapacitated.
Actions
Dagger
Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: (1d4 + 2) piercing damage.
Sling
Ranged Weapon Attack: +4 to hit, reach 30/120 ft., one target. Hit: (1d4 + 2) bludgeoning damage.
This is just one way you could have opted to mark up that statblock.
I love this as a demonstration because it really goes to show just how versatile the description list pattern can really be — the lists of ability scores (STR, DEX, and so forth) and attacks both look very different, and yet, the description list pattern can span them all.
Takeaways
Lists of name–value pairs (or, in some cases, name–value groups) are a common pattern across the web, in part due to their versatility. HTML lets us mark up these lists with a combination of three elements:
The
, or description list, element, which wraps the entire list of name–value pairs
The
, or description term, element, which represents a name in our name–value pairs
The
, or description detail, element, which represents a value in our name–value pairs
Ascribing semantics to patterns such as these gives our users’ devices the information they need to curate useful, usable experiences — oftentimes in ways that we as developers may not expect.
To learn more about description lists and what’s allowed or not allowed, I recommend the MDN docs on the
, or going directly to the specs!
Footnotes
Prior to HTML5, this was called a definition list. This is because the
was originally only intended to represent glossaries of terms and their definitions. | Back to [1]
Prior to HTML5, this was called a definition list. This is because the
was originally only intended to represent glossaries of terms and their definitions. | Back to [1]
Previously known as the definition term and definition detail elements respectively. | Back to [2]
Previously known as the definition term and definition detail elements respectively. | Back to [2]
.
We start with our
. This is the description list,[note 1] akin to using a
for an unordered list or an
for an ordered list.
Fancy.
Next up, we want to add a name–value pair. We’ll use a
, short for description term, for the name, and we’ll use a
, short for description detail, for the value.[note 2]
Title
Designing with Web Standards
Title
Designing with Web Standards
To add another name–value pair to our list, we add another
and
:
Title
Designing with Web Standards
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
But wait — what if I have a term that has multiple values? For instance, what if this book has multiple authors?
That’s fine! One
can have multiple
s:
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
There’s one last piece of the description list anatomy to look at for most basic use cases: what if I want to wrap a
and its
(s) for styling reasons?
In this case, the specs allow you to wrap a
and its
(s) in a
:
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
A wrapper
like this is the only element that can wrap those
/
groups.
And that’s it! That’s the anatomy of the description list, HTML's semantic way to mark up a list of name–value groups!
Why Do We Need Semantics For This Anyways?
Before we learned about the
,
, and
elements, my team used to use nested
s for this pattern all the time. It looked a lot like:
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
Title
Designing with Web Standards
Author
Jeffrey Zeldman
Ethan Marcotte
Publisher
New Riders Pub; 3rd edition (October 19, 2009)
This has all the information about the book, right? Why do we need semantics for a list of name–value groups in the first place if something like a series of nested
s could get the job done?
When determining whether a semantic element might be appropriate for a given pattern, I find it helpful to ask, “What benefits — even theoretical — could we get if computers could recognize this pattern?” In this case, what lift could we get if browsers could somehow recognize a list of name–value groups?
Answers to that question will be varied. I tend to spend a lot of time advocating for web accessibility, so my first thought tends to be how screenreaders could interpret the pattern. Off the top of my head, I can think of a couple of benefits screenreader users could get from their screenreaders recognizing this pattern:
The screenreader could tell the user how many name–value groups are in the list.
The screenreader could tell the user how far into the list they are.
The screenreader could treat the list as one block that the user could skip over if they’re uninterested in it.
All of these could make the list more usable than a series of nested
s, which would treat each name and value in the list as nothing more than a standalone text node.
If you can come up with a couple of even theoretical lifts from the user’s device recognizing a pattern, then there’s a good chance that the pattern is a strong candidate for having some associated semantics.
For what it’s worth, these screenreader experiences aren’t hypothetical — they’re benefits that screenreader users really get from using
in most browser/screenreader combinations. Admittedly, however, support for the
element is not yet universal. You may decide that screenreaders’ fallback experience — treating the list as standalone text nodes — isn’t sufficient for your use case, and instead opt for something like a
until support improves.
Okay, Okay, One Last Example!
My favorite example, the one that really takes the cake for me, is Dungeons & Dragons statblocks, which are really “Oops! All Name–Value Pairs!”
No, really: just how many candidates for
s do you see in this statblock alone?
I counted five possible description lists, personally. Here’s how I chose to mark this up:
Kobold
Small humanoid (kobold), lawful evil
Armor Class
12
Hit Points
5 (2d6 - 2)
Speed
30 ft.
STR
7 (-2)
DEX
15 (+2)
CON
9 (-1)
INT
8 (-1)
WIS
7 (-2)
CHA
8 (–1)
Senses
Darkvision 60 ft.
Passive Perception 8
Languages
Common
Draconic
Challenge
1/8 (25 XP)
Sunlight Sensitivity
While in sunlight, the kobold has disadvantage on attack rolls, as well as on Wisdom (Perception) checks that rely on sight.
Pack Tactics
The kobold has advantage on an attack roll against a creature if at least one of the kobold's allies is within 5 ft. of the creature and the ally isn't incapacitated.
Actions
Dagger
Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: (1d4 + 2) piercing damage.
Sling
Ranged Weapon Attack: +4 to hit, reach 30/120 ft., one target. Hit: (1d4 + 2) bludgeoning damage.
Kobold
Small humanoid (kobold), lawful evil
Armor Class
12
Hit Points
5 (2d6 - 2)
Speed
30 ft.
STR
7 (-2)
DEX
15 (+2)
CON
9 (-1)
INT
8 (-1)
WIS
7 (-2)
CHA
8 (–1)
Senses
Darkvision 60 ft.
Passive Perception 8
Languages
Common
Draconic
Challenge
1/8 (25 XP)
Sunlight Sensitivity
While in sunlight, the kobold has disadvantage on attack rolls, as well as on Wisdom (Perception) checks that rely on sight.
Pack Tactics
The kobold has advantage on an attack roll against a creature if at least one of the kobold's allies is within 5 ft. of the creature and the ally isn't incapacitated.
Actions
Dagger
Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: (1d4 + 2) piercing damage.
Sling
Ranged Weapon Attack: +4 to hit, reach 30/120 ft., one target. Hit: (1d4 + 2) bludgeoning damage.
This is just one way you could have opted to mark up that statblock.
I love this as a demonstration because it really goes to show just how versatile the description list pattern can really be — the lists of ability scores (STR, DEX, and so forth) and attacks both look very different, and yet, the description list pattern can span them all.
Takeaways
Lists of name–value pairs (or, in some cases, name–value groups) are a common pattern across the web, in part due to their versatility. HTML lets us mark up these lists with a combination of three elements:
The
, or description list, element, which wraps the entire list of name–value pairs
The
, or description term, element, which represents a name in our name–value pairs
The
, or description detail, element, which represents a value in our name–value pairs
Ascribing semantics to patterns such as these gives our users’ devices the information they need to curate useful, usable experiences — oftentimes in ways that we as developers may not expect.
To learn more about description lists and what’s allowed or not allowed, I recommend the MDN docs on the
, or going directly to the specs!
Footnotes
Prior to HTML5, this was called a definition list. This is because the
was originally only intended to represent glossaries of terms and their definitions. | Back to [1]
Prior to HTML5, this was called a definition list. This is because the
was originally only intended to represent glossaries of terms and their definitions. | Back to [1]
Previously known as the definition term and definition detail elements respectively. | Back to [2]
Previously known as the definition term and definition detail elements respectively. | Back to [2]