Dec 14

Details / Summary

The details and summary pair of HTML elements provide a native disclosure pattern, no extra JavaScript required!

By Stephanie Eckles

Using details and summary is appropriate to reveal (aka "disclose") supplemental information. However, there is a fine line between acceptable and inaccessible usage. While we won't dive into that in this post, be sure to check the additional resources for more information.

Setting up details and summary

Here is the most essential markup for this pattern. The details element is the parent, and the first child is the summary.

<details>
<summary>Summary text</summary>
<p>The content that appears when the details element is open</p>
</details>

Which produces the following, which is shown using default browser styles:

Summary text

The content that appears when the details element is open

You can also predefine that the details should be open which means the full content is revealed as the default state.

Important to note: you have to remove the open attribute completely to close the details, not just set it to "false".

<details open>
<summary>Open summary text</summary>
<p>This content is visible by default</p>
</details>
Open summary text

This content is visible by default

When the details element open attribute is toggled, it emits a "toggle" event that you can listen for in JavaScript. You can also programmatically add or remove the open attribute.

JS for the details "toggle" event
const details = document.querySelector('.js-ds');
details.addEventListener('toggle', event => {
const summary = details.querySelector('summary');
if (details.open) {
summary.style.backgroundColor = 'pink';
} else {
summary.style.backgroundColor = 'tomato';
}
});
Background will change on toggle

Pie wafer apple pie jelly cotton candy chocolate bar icing jelly beans. Apple pie shortbread carrot cake cupcake pastry gummi bears chupa chups lollipop.

Styling considerations for details and summary

One of the main issues with browser (aka user agent) styles is that they don't ship with very good focus or hover indicators to reinforce the interactivity. So, let's fix those two items up first. These styles will be attached to the summary since that receives those states.

CSS for summary hover and focus
summary.styled {
/* Provide a more expected visual affordance for this clickable element */
cursor: pointer;
}

summary.styled:hover {
background-color: #ddd;
}

summary.styled:focus {
outline: 2px solid currentColor;
outline-offset: 2px;
}
I have style!

Gummies topping topping lollipop shortbread candy canes sweet roll. Topping lemon drops sweet muffin lemon drops tootsie roll chupa chups sesame snaps caramels.

We can take it further by customizing the native arrow indicator thanks to a modern CSS selector for ::marker (which also can style list bullets).

CSS for styling the summary ::marker
summary.styled--marker::marker {
color: magenta;
}
Even more stylish!

Gummies topping topping lollipop shortbread candy canes sweet roll. Topping lemon drops sweet muffin lemon drops tootsie roll chupa chups sesame snaps caramels.

Ways to use details and summary

Additional Resources

Due to there being a narrow range for ensuring your use of details and summary is accessible, I encourage you to check out Adrian Roselli's post on Disclosure Widgets. You'll learn about a few other similar patterns that would not be appropriate to use details and summary, and also find the very simple JS and CSS required if you choose to roll your own.