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%2Fsummary.html | |
new repository
Diffstat (limited to 'devdocs/html/element%2Fsummary.html')
| -rw-r--r-- | devdocs/html/element%2Fsummary.html | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/devdocs/html/element%2Fsummary.html b/devdocs/html/element%2Fsummary.html new file mode 100644 index 00000000..0c9ddf94 --- /dev/null +++ b/devdocs/html/element%2Fsummary.html @@ -0,0 +1,145 @@ +<header><h1><summary>: The Disclosure Summary element</h1></header><div class="section-content"><p>The <code><summary></code> <a href="../index">HTML</a> element specifies a summary, caption, or legend for a <a href="details"><code><details></code></a> element's disclosure box. Clicking the <code><summary></code> element toggles the state of the parent <code><details></code> element open and closed.</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"><iframe class="interactive is-tabbed-shorter-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/summary.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe></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="usage_notes">Usage notes</h2> +<div class="section-content"> +<p>The <code><summary></code> element's contents can be any heading content, plain text, or HTML that can be used within a paragraph.</p> <p>A <code><summary></code> element may <em>only</em> be used as the first child of a <code><details></code> element. When the user clicks on the summary, the parent <code><details></code> element is toggled open or closed, and then a <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDetailsElement/toggle_event"><code>toggle</code></a> event is sent to the <code><details></code> element, which can be used to let you know when this state change occurs.</p> +</div> +<h3 id="default_label_text">Default label text</h3> +<div class="section-content"><p>If a <code><details></code> element's first child is not a <code><summary></code> element, the <a href="https://developer.mozilla.org/en-US/docs/Glossary/User_agent">user agent</a> will use a default string (typically "Details") as the label for the disclosure box.</p></div> +<h3 id="default_style">Default style</h3> +<div class="section-content"> +<p>Per the HTML specification, the default style for <code><summary></code> elements includes <code>display: list-item</code>. This makes it possible to change or remove the icon displayed as the disclosure widget next to the label from the default, which is typically a triangle.</p> <p>You can also change the style to <code>display: block</code> to remove the disclosure triangle.</p> <p>See the <a href="#browser_compatibility">Browser compatibility</a> section for details, as not all browsers support full functionality of this element yet.</p> <p>For Webkit-based browsers, such as Safari, it is possible to control the icon display through the non-standard CSS pseudo-element <code>::-webkit-details-marker</code>. To remove the disclosure triangle, use <code>summary::-webkit-details-marker { display: none }</code>.</p> +</div> +<h2 id="examples">Examples</h2> +<div class="section-content"><p>Below are some examples showing <code><summary></code> in use. You can find more examples in the documentation for the <a href="details"><code><details></code></a> element.</p></div> +<h3 id="basic_example">Basic example</h3> +<div class="section-content"> +<p>A simple example showing the use of <code><summary></code> in a <a href="details"><code><details></code></a> element:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="HOi2ZMwsCOmar8ZW4jXf0UP8OWDhVzDcw+qVxj+nsTc=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>details</span> <span class="token attr-name">open</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>summary</span><span class="token punctuation">></span></span>Overview<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>summary</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ol</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Cash on hand: $500.00<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Current invoice: $75.30<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Due date: 5/6/19<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ol</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>details</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="Basic example sample" id="frame_basic_example" width="650" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/summary/runner.html?id=basic_example" loading="lazy"></iframe> +</div> +</div> +<h3 id="summaries_as_headings">Summaries as headings</h3> +<div class="section-content"> +<p>You can use heading elements in <code><summary></code>, like this:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="QYs9cS9qT5lDdKD90eqaZI0990MugbN0Xcb3s1Q9vCo=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>details</span> <span class="token attr-name">open</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>summary</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h4</span><span class="token punctuation">></span></span>Overview<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>h4</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>summary</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ol</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Cash on hand: $500.00<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Current invoice: $75.30<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Due date: 5/6/19<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ol</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>details</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="Summaries as headings sample" id="frame_summaries_as_headings" width="650" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/summary/runner.html?id=summaries_as_headings" loading="lazy"></iframe> +</div> <p>This currently has some spacing issues that could be addressed using CSS.</p> <div class="notecard warning" id="sect3"> <p><strong>Warning:</strong> Because the <code><summary></code> element has a default role of <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role">button</a> (which strips all roles from child elements), this example will not work for users of assistive technologies such as screen readers. The <code><h4></code> will have its role removed and thus will not be treated as a heading for these users.</p> </div> +</div> +<h3 id="html_in_summaries">HTML in summaries</h3> +<div class="section-content"> +<p>This example adds some semantics to the <code><summary></code> element to indicate the label as important:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="Kcy7ZpB8/IzP+mSsQnLGfXDvAVyBzhM22Y1FtipSovk=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>details</span> <span class="token attr-name">open</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>summary</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>strong</span><span class="token punctuation">></span></span>Overview<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>strong</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>summary</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ol</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Cash on hand: $500.00<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Current invoice: $75.30<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span>Due date: 5/6/19<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ol</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>details</span><span class="token punctuation">></span></span> +</pre> +</div> <h4 id="result_3">Result</h4> +<div class="code-example" id="sect4"> + +<iframe class="sample-code-frame" title="HTML in summaries sample" id="frame_html_in_summaries" width="650" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/summary/runner.html?id=html_in_summaries" loading="lazy"></iframe> +</div> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row">Permitted content</th> <td> <a href="../content_categories#phrasing_content">Phrasing content</a> or one element of <a href="../content_categories#heading_content">Heading content</a> </td> </tr> <tr> <th scope="row">Tag omission</th> <td>None; both the start tag and the end tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td>The <a href="details"><code><details></code></a> element.</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>No <code>role</code> permitted</td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"><code>HTMLElement</code></a></td> </tr> </tbody> </table></div></figure></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/interactive-elements.html#the-summary-element">HTML Standard <br><small># the-summary-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>summary</code></th> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">79</td> +<td class="bc-supports-yes">49</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">15</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">49</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.0</td> +</tr> +<tr> +<th><code>display_list_item</code></th> +<td class="bc-supports-yes">89</td> +<td class="bc-supports-yes">89</td> +<td class="bc-supports-yes">49</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">75</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">89</td> +<td class="bc-supports-yes">89</td> +<td class="bc-supports-yes">49</td> +<td class="bc-supports-yes">63</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">15.0</td> +</tr> +</tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li><a href="details"><code><details></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/summary" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary</a> + </p> +</div> |