Just Details; No Devil

Have you ever needed to code a series of collapsible pieces of content? Maybe some FAQs or some “accordion” components to allow readers to dig more deeply into content that was more relevant for them? In agencies or client-facing work, these might be called accordions, collapsible panels, toggled content, plus/minus menus, or something else.

Chances are, you reached for some JavaScript to do that. Maybe you used a definition list (dl) with click events on all the definition term (dt) elements? If you were concerned with accessibility, you might have toggled aria-expanded on each affected definition details (dd) element. At this point, you’re handling a significant amount of complexity: semantic markup, JS event/state handling, accessibility attribute management.

What if I told you that browsers can natively handle this collapsed-content behavior?

Enter the details element (and its bff: summary):

Introducing `details`

The details element is a pretty useful HTML element that handles collapsible content natively.

Using details is pretty straightforward: you wrap a details element around any block of HTML content. The browser will collapse that block of content until a user expands it.

<details>Here’s some content that might not be useful to <i>everyone</i> so we’ve "hidden” it in a details block till a user expands it.</details>

Once a user opens a details block, they’ll be able to read all that hidden content.

If you want a specific details block to be open by default, set the open attribute on the opening tag:

<details open>All of this content will be expanded by default. A user can still collapse this block if they want to.</details>

Custom Titles with `summary`

By default, browsers give a details element a generic “Details” title. You can customize that with the summary element.

Put a summary at the beginning of your details element and Boom! - you’ve got a custom title for your details block.

<details>
  <summary>More information about this topic</summary>
  <p>Here’s a lot more information about the topic at hand!</p>
</details>

Styling `details` and `summary`

You can style the details and summary elements however you like. Set a border, some padding, whatever your designs call for.

Removing the `summary` icon

The summary element is where the ▸ marker lives. If you want to get rid of that, there is a prefixed pseudo-element selector: ::-webkit-details-marker. Set that to display: none for WebKit browsers.

In Firefox and Edge, it’s a bit different. Change the summary’s display value to anything but its native list-item; then the ▸ will be removed.

/* Firefox & Edge */
summary {
  display: block;
}
/* Safari & Chrome */
::webkit-details-marker {
  display: none;
}

Styling open and closed states

When a details block is open, it has the open attribute that I mentioned earlier. To style it (or its children) based on its state, use details[open].

details[open] {
  box-shadow: 0 0 5px black;
}

Note: there’s no closed attribute. Any styles you apply without the [open] selector scope will be used on the closed state.

JavaScript, Accessibility, and Support

No JavaScript required

It may seem too good to be true, but in supporting browsers, no JS is needed to make details work. There are a few scenarios that would require JS:

Proper behavior in a browser without support
Forcing open details to collapse when a user opens another one

Accessible by default

Since details and summary are native HTML elements, they provide useful semantic information to screen readers.

Screen readers will typically read the summary for a collapsed details block (and communicate that it’s collapsed). They’ll also provide an interactive hook for users to open the details block. If the details is already expanded, they’ll read the whole content.

I don’t rely on assistive tech to read the web, so I may be unaware of some limitations or drawbacks to using details and summary, but I suspect their assistive tech user experience is at least as good as (if not better than) most JavaScript-dependent accordion solutions.

Browser support

Unfortunately, details and summary don’t work in IE or Edge. They are supported in Firefox (since 49: 2016), Chrome (since 6: 2011), Safari (since 6: 2012), and Android (since 4: 2011). Check out caniuse data for details and summary.

Non-supporting browsers don’t collapse/expand. They show all the contents like a block-level element. This is a very nice bit of progressive enhancement: if a user’s browser doesn’t support details and summary, they can still read all the content and custom styles are still applied.

You’ll want to be careful to remove any interactive affordances in IE and Edge: don’t show a user toggle icons for something that won’t move. You can include a JS polyfill if the behavior is necessary.

It’s unlikely IE11 will be getting any updates on this front, but there’s hope for Edge! If this is important to you, please cast a vote a vote for Edge to support details and summary..

Additional Resources

If you’d like to continue learning about details and summary, here’s a list of resources that will be helpful to you:

DockYard is a digital product agency offering exceptional strategy, design, full stack engineering, web app development, mobile development, custom software, Ember, Elixir, and Phoenix services. With a nationwide staff, we’ve got consultants in key markets across the United States including Seattle, Los Angeles, Denver, Chicago, Atlanta, New York, and Boston.

Introducing details

Custom Titles with summary

Styling details and summary

Removing the summary icon