Details / Summary

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.

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:

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>

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.

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';
  }
});

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.

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;
}

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).

summary.styled--marker::marker {
  color: magenta;
}

• FAQs as long as you aren't intending them to be an accordion, which would be an inaccessible use case
• A tangential fact within a longer post
• An audio or video full transcript
• Allowing expanding/collapsing code snippets related to a demo as you'll see throughout this site

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.