Discover how the very useful details and summary elements work, and where to use them.

An expander arrow, sometimes known as a disclosure widget, is a user interfacecontrol that hides and shows content. If you are reading this onweb.dev, andyour viewport is less than 106 ems wide, clicking the "On this page" reveals thetable of contents for this section. If you don't see it, shrink the browser toview the table of contents navigation on this page as an expander arrow.

Theaccordion graphical userinterface is a series of vertically stacked disclosure widgets. A common usecase for the accordion is a Frequently Asked Questions (FAQ) page. In this case,an accordion FAQ contains a list of visible questions. When clicked on, thequestion expands, or "discloses," the answer to that question.

jQuery has included an accordion UI patternsince at least 2009. The original JavaScript-free accordion solution includedmaking each FAQ question a<label> followed by the checkmark it labeled, andthen displaying<div> answer when the checkmark was checked. The CSS lookedsomething like this:

#FAQ[type="checkbox"]+div.answer{/* all the answer styles */display:none;}#FAQ[type="checkbox"]:checked+div.answer{display:block;}

Why the history? Disclosure widgets, such as accordions, without JavaScript orform control hacks, are a relatively recent addition. The<details> and<summary>elements have only been fully supported in modern browsers since January 2020.You can now create functional, albeit less than attractive, disclosure widgetswith semantic HTML.

The<details> and<summary> elements are all you need: they are abuilt-in way to handle expanding and collapsing content. When a user clicks ortaps a<summary>, or releases theEnter key when the<summary>has focus, the contents of the parent<details> toggle to visible.

Like all semantic content, you can progressively enhance the default featuresand appearance. In this case, just a tiny bit of CSS has been added:

That means, this CodePen (and all of the CodePen samples) has no JavaScript.

Toggle visibility with theopen attribute

The<details> element is the disclosure widget container. The<summary> isthe summary or legend for its parent<details>. The summary is alwaysdisplayed, acting as a button that toggles the display of the rest of theparent's contents. Interacting with the<summary> toggles the display of theself-labeled summary siblings by toggling the<details>' element'sopenattribute.

Theopen attribute is a boolean attribute. If present, no matter the valueor lack thereof, it indicates that all the<details> contents are shown tothe user. If theopen attribute is not present, only the contents of the<summary> are shown.

Because theopen attribute is added and removed automatically as the userinteracts with the control, it can be used in CSS to style the elementdifferently based on its state.

You can create an accordion with a list of multiple<details> elements, eachwith a<summary> child. Omitting theopen attribute in your HTML means the<details> will all be collapsed, or closed, with just the summary headingsvisible when the page loads;each heading being the opener for the rest of the contents in the parent<details>. If you include theopen attribute in your HTML,<details>renders expanded, with the contents visible, when the page loads.

The hidden content in the collapsed state is searchable in some browsers butnot others, even though the collapsed content is not part of the DOM. If yousearch in Edge or Chrome, the details containing a search term expand to displaythe occurrence. This behavior is not replicated in Firefox or Safari.

The<summary> must be the first child of a<details> element, representinga summary, caption, or legend for the rest of the contents of the parent<details> element in which it is nested. The<summary> element's contentscan be any heading content, plain text, or HTML that can be used within aparagraph.

Toggle the summary marker

In the two earlier Codepens, there's an arrow to theinline-startside of the summary. An expander arrow is typically presented on-screen, asmall triangle that rotates (or twists) to indicate open or closed status anda label next to the triangle. The contents of the<summary> element label thedisclosure widget.

The rotating arrow at the top of each section is a::marker set on the<summary> element. Like list items, the<summary> element supports thelist-styleshorthand property and its longhand properties, includinglist-style-type.You can style the disclosure triangle with CSS, including changing the markerused from a triangle to any other bullet type, including an image withlist-style-image.

To apply other styles, use a selector similar todetails summary::marker. The::markerpseudo-element only accepts a limitednumber of styles. Removing the::marker and replacing it with theeasier-to-style::beforeis common practice, with CSS styles changing the style of the generated contentslightly based on the presence (or absence) of the open attribute. You canremove the disclosure widget icon by settinglist-style: none or set thecontentof the marker tonone, but you should always include visual indicators toinform sighted users that the summary content toggles to show and hide content.

detailssummary::before{/* all the styles */}details[open]summary::before{/* changes applied when open only */}

This example removes the default marker, and adds generated content to create a+ when the details are closed and a- when the details are open.

If you want the details block open by default, include theopen attribute onthe opening<details> tag. You can also add space between each dialog andtransition the rotation of the marker created with generated content toimprove the appearance:

How errors are handled

If you don't include a<summary>, the browser creates one for you, with amarker and the word "details". This summary is part of ashadow root, and therefore doesn't haveauthor CSS summary styles applied.

If you do include a<summary>, but it's not the first element in the<details>, the browser still displays the summary as it should. It won't failif you include a link, label, or other interactive element within the summarybut browsers handle interactive content within interactive content differently.

For example, if you include a link in a summary, some browsers add both thesummary and the link to the default tabbing order, but other browsers don'tfocus on the link by default. If you click a<label> nested in a<summary>,some browsers give focus to the associated form control. Other browsersgive focus to the form control and toggle the<details> open or closed.

TheHTMLDetailsElement interface

Like all HTML elements, theHTMLDetailsElementinherits all properties, methods, and events fromHTMLElement, andadds theopeninstance property and atoggleevent. TheHTMLDetailsElement.openproperty is a boolean value reflecting theopenHTML attribute, indicating whether or not the element's contents(not counting the<summary>) are to be shown to the user. The toggle event isfired when the<details> element is toggled open or closed. You can listen tothis event usingaddEventListener().

If you want to write a script to close the opened details when the user opensany other details, remove the open attribute usingremoveAttribute("open"):

This is the only example to use JavaScript. You probably don't need JavaScript,except to close other open widgets.

Remember,<details> and<summary> can be heavily styled and can even be usedtocreate tooltips.But, if you're going to use these semantic elements for use cases in which thenative semantics are a mismatch, alwaysmaintain accessibility.HTML for the most part is by default accessible. Our job as developers is tomake sure our content stays accessible.

Check your understanding

Test your knowledge of details and summary.