1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<header><h1><dl>: The Description List element</h1></header><div class="section-content"><p>The <code><dl></code> <a href="../index">HTML</a> element represents a description list. The element encloses a list of groups of terms (specified using the <a href="dt"><code><dt></code></a> element) and descriptions (provided by <a href="dd"><code><dd></code></a> elements). Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).</p></div>
<h2 id="try_it">Try it</h2>
<div class="section-content">
<iframe class="interactive is-tabbed-standard-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/dl.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td> <a href="../content_categories#flow_content">Flow content</a>, and if the <code><dl></code> element's children include one name-value group, palpable content. </td> </tr> <tr> <th scope="row">Permitted content</th> <td> <p> Either: Zero or more groups each consisting of one or more <a href="dt"><code><dt></code></a> elements followed by one or more <a href="dd"><code><dd></code></a> elements, optionally intermixed with <a href="script"><code><script></code></a> and <a href="template"><code><template></code></a> elements.<br>Or: (in <a href="https://developer.mozilla.org/en-US/docs/Glossary/WHATWG">WHATWG</a> HTML, <a href="https://developer.mozilla.org/en-US/docs/Glossary/W3C">W3C</a> HTML 5.2 and later) One or more <a href="div"><code><div></code></a> elements, optionally intermixed with <a href="script"><code><script></code></a> and <a href="template"><code><template></code></a> elements. </p> </td> </tr> <tr> <th scope="row">Tag omission</th> <td>None, both the starting and ending tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td> Any element that accepts <a href="../content_categories#flow_content">flow content</a>. </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" target="_blank">No corresponding role</a></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td> <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <code><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/list_role">list</a></code>, <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> </td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDListElement"><code>HTMLDListElement</code></a></td> </tr> </tbody> </table></div></figure>
</div>
<h2 id="attributes">Attributes</h2>
<div class="section-content"><p>This element only includes the <a href="../global_attributes">global attributes</a>.</p></div>
<h2 id="examples">Examples</h2>
<h3 id="single_term_and_description">Single term and description</h3>
<div class="section-content">
<div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="M2KB6BAn11nEoejo3yfJckht/P+TUmFXQBI5qSDOJ30=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dl</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Firefox<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>
A free, open source, cross-platform, graphical web browser developed by the
Mozilla Corporation and hundreds of volunteers.
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token comment"><!-- Other terms and descriptions --></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dl</span><span class="token punctuation">></span></span>
</pre>
</div> <h4 id="result">Result</h4>
<div class="code-example" id="sect1">
<iframe class="sample-code-frame" title="Single term and description sample" id="frame_single_term_and_description" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dl/runner.html?id=single_term_and_description" loading="lazy"></iframe>
</div>
</div>
<h3 id="multiple_terms_single_description">Multiple terms, single description</h3>
<div class="section-content">
<div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="r70kadJajGwLcDcHd4FV8dfWdIwl2ddLtbWMVHd1L4M=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dl</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Firefox<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Mozilla Firefox<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Fx<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>
A free, open source, cross-platform, graphical web browser developed by the
Mozilla Corporation and hundreds of volunteers.
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token comment"><!-- Other terms and descriptions --></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dl</span><span class="token punctuation">></span></span>
</pre>
</div> <h4 id="result_2">Result</h4>
<div class="code-example" id="sect2">
<iframe class="sample-code-frame" title="Multiple terms single description sample" id="frame_multiple_terms_single_description" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dl/runner.html?id=multiple_terms_single_description" loading="lazy"></iframe>
</div>
</div>
<h3 id="single_term_multiple_descriptions">Single term, multiple descriptions</h3>
<div class="section-content">
<div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="2wkvGqjOgJk7dQZOFONstJAg6gD1mzw5/PkNeNkbSPA=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dl</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Firefox<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>
A free, open source, cross-platform, graphical web browser developed by the
Mozilla Corporation and hundreds of volunteers.
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>
The Red Panda also known as the Lesser Panda, Wah, Bear Cat or Firefox, is a
mostly herbivorous mammal, slightly larger than a domestic cat (60 cm long).
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token comment"><!-- Other terms and descriptions --></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dl</span><span class="token punctuation">></span></span>
</pre>
</div> <h4 id="result_3">Result</h4>
<div class="code-example" id="sect3">
<iframe class="sample-code-frame" title="Single term multiple descriptions sample" id="frame_single_term_multiple_descriptions" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dl/runner.html?id=single_term_multiple_descriptions" loading="lazy"></iframe>
</div>
</div>
<h3 id="multiple_terms_and_descriptions">Multiple terms and descriptions</h3>
<div class="section-content"><p>It is also possible to define multiple terms with multiple corresponding descriptions, by combining the examples above.</p></div>
<h3 id="metadata">Metadata</h3>
<div class="section-content">
<p>Description lists are useful for displaying metadata as a list of key-value pairs.</p> <div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="ggC1gFkDvO6JFAhoN3EqxIwXHU9xb2iS+jCZJURc0aI=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dl</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Name<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Godzilla<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Born<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>1952<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Birthplace<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Japan<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Color<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Green<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dl</span><span class="token punctuation">></span></span>
</pre>
</div> <h4 id="result_4">Result</h4>
<div class="code-example" id="sect4">
<iframe class="sample-code-frame" title="Metadata sample" id="frame_metadata" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dl/runner.html?id=metadata" loading="lazy"></iframe>
</div> <p>Tip: It can be handy to define a key-value separator in the CSS, such as:</p> <div class="code-example">
<p class="example-header"><span class="language-name">css</span></p>
<pre data-signature="+1HiRyGoTWLoL9dc9hWcGgNcU1bY9VCCK8Vw6JPkpBY=" data-language="css"><span class="token selector">dt::after</span> <span class="token punctuation">{</span>
<span class="token property">content</span><span class="token punctuation">:</span> <span class="token string">": "</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</pre>
</div>
</div>
<h3 id="wrapping_name-value_groups_in_div_elements">Wrapping name-value groups in <code>div</code> elements</h3>
<div class="section-content">
<p><a href="https://developer.mozilla.org/en-US/docs/Glossary/WHATWG">WHATWG</a> HTML allows wrapping each name-value group in a <a href="dl" aria-current="page"><code><dl></code></a> element in a <a href="div"><code><div></code></a> element. This can be useful when using <a href="../microdata">microdata</a>, or when <a href="../global_attributes">global attributes</a> apply to a whole group, or for styling purposes.</p> <div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="QCqvOoQtxNieexVFq+A7+T0VrsJ3whs6tVqRt06AeIQ=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dl</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Name<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Godzilla<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Born<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>1952<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Birthplace<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Japan<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dt</span><span class="token punctuation">></span></span>Color<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dt</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dd</span><span class="token punctuation">></span></span>Green<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dd</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dl</span><span class="token punctuation">></span></span>
</pre>
</div> <h4 id="result_5">Result</h4>
<div class="code-example" id="sect5">
<iframe class="sample-code-frame" title="Wrapping name-value groups in `div` elements sample" id="frame_wrapping_name-value_groups_in_div_elements" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dl/runner.html?id=wrapping_name-value_groups_in_div_elements" loading="lazy"></iframe>
</div>
</div>
<h2 id="notes">Notes</h2>
<div class="section-content">
<p>Do not use this element (nor <a href="ul"><code><ul></code></a> elements) to merely create indentation on a page. Although it works, this is a bad practice and obscures the meaning of description lists.</p> <p>To change the indentation of a description term, use the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS">CSS</a> <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/margin"><code>margin</code></a> property.</p>
</div>
<h2 id="accessibility_concerns">Accessibility concerns</h2>
<div class="section-content">
<p> Each screen reader exposes <code><dl></code> content differently, including total count, terms/definitions context, and navigation methods. These differences are not necessarily bugs. As of iOS 14, VoiceOver will announce that <code><dl></code> content is a list when navigating with the virtual cursor (not via the read-all command). VoiceOver does not support list navigation commands with <code><dl></code>. Be careful applying ARIA <code>term</code> and <code>definition</code> roles to <code><dl></code> constructs as VoiceOver (macOS and iOS) will adjust how they are announced. </p> <ul> <li><a href="https://adrianroselli.com/2020/09/voiceover-on-ios-14-supports-description-lists.html" target="_blank">VoiceOver on iOS 14 Supports Description Lists</a></li> <li><a href="https://adrianroselli.com/2022/12/brief-note-on-description-list-support.html" target="_blank">Brief Note on Description List Support</a></li> </ul>
</div>
<h2 id="specifications">Specifications</h2>
<div class="_table"><table class="standard-table">
<thead><tr><th scope="col">Specification</th></tr></thead>
<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element">HTML Standard <br><small># the-dl-element</small></a></td></tr></tbody>
</table></div>
<h2 id="browser_compatibility">Browser compatibility</h2>
<div class="_table"><table>
<thead>
<tr id="bct-browser-type">
<th></th>
<th colspan="6">Desktop</th>
<th colspan="6">Mobile</th>
</tr>
<tr id="bct-browsers">
<th></th>
<th>Chrome</th>
<th>Edge</th>
<th>Firefox</th>
<th>Internet Explorer</th>
<th>Opera</th>
<th>Safari</th>
<th>WebView Android</th>
<th>Chrome Android</th>
<th>Firefox for Android</th>
<th>Opera Android</th>
<th>Safari on IOS</th>
<th>Samsung Internet</th>
</tr>
</thead>
<tbody><tr>
<th><code>dl</code></th>
<td class="bc-supports-yes">1</td>
<td class="bc-supports-yes">12</td>
<td class="bc-supports-yes">1</td>
<td class="bc-supports-yes">Yes</td>
<td class="bc-supports-yes">15</td>
<td class="bc-supports-yes">≤4</td>
<td class="bc-supports-yes">4.4</td>
<td class="bc-supports-yes">18</td>
<td class="bc-supports-yes">4</td>
<td class="bc-supports-yes">14</td>
<td class="bc-supports-yes">≤3.2</td>
<td class="bc-supports-yes">1.0</td>
</tr></tbody>
</table></div>
<h2 id="see_also">See also</h2>
<div class="section-content"><ul> <li><a href="dt"><code><dt></code></a></li> <li><a href="dd"><code><dd></code></a></li> </ul></div><div class="_attribution">
<p class="_attribution-p">
© 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br>
<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl</a>
</p>
</div>
|
