diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/html/element%2Fdl.html | |
new repository
Diffstat (limited to 'devdocs/html/element%2Fdl.html')
| -rw-r--r-- | devdocs/html/element%2Fdl.html | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/devdocs/html/element%2Fdl.html b/devdocs/html/element%2Fdl.html new file mode 100644 index 00000000..62b7322b --- /dev/null +++ b/devdocs/html/element%2Fdl.html @@ -0,0 +1,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> |