Here is what the spec has to say about <details>:

The details element represents a disclosure widget from which the user can obtain additional information or controls.

Essentially, we can use <details> to create an accordion-like widget that the user can toggle open and closed. Inside <details>, we can put any sort of content we want.

Browser support

Before we go any further, you should know that currently, only Chrome supports the <details> element. Opera will support it soon, but in the meantime we’ll have to use some polyfills. So fire up Chrome and let’s take a peek.

Using <details>

There are two relevant elements here: <details> and, optionally, <summary>. <details> is the wrapper for all the content we want to show and hide, and <summary> contains the — well, the summary and title of the section. Technically we don’t need the <summary>. If absent, the browser will use some default text (in Chrome: “details”). Let’s have a look at some markup:

<details>
  <summary>Show/Hide me</summary>
  <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
</details>

You can see this in action over at jsbin. It’s a simple example, but it shows off the toggle effect nicely. All this without JavaScript!

The open attribute

In the example above, the content is hidden when the page loads. We can make it visible by default by adding the boolean open attribute to the <details> element (jsbin example):

<details open>
  <summary>Show/Hide me</summary>
  <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
</details>

There is no closed attribute. It’s the default, so by omitting open, you imply closed.

The <summary> element

We’ve briefly seen <summary> in action. Since it is phrasing content, we can use inline elements such as <span> or <strong> inside it. Why thought would we do this? Perhaps for an extra styling hook or as the spec suggests: a label for a form element. At least it would be handy if it worked properly when implemented:

<details>
  <summary><label for="name">Name:</label></summary>
  <input type="text" id="name" name="name" />
</details>

Normally, clicking anywhere on the summary reveals the content of the <details> element. But in this example, clicking the summary doesn’t reveal the content because you’re actually clicking the <label>, which then focuses the <input> element — even though it’s hidden by the collapsed <details> element.

Clearly this needs addressing, what do you think should happen? Maybe any browser vendors reading this can take a look :)

Nesting multiple <details> elements

You can nest <details> within <details> if you like, as seen in this perfectly valid example:

<details>
  <summary>Question 1</summary>
  <p><strong>Pellentesque habitant morbi tristique</strong> senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. <a href="#">Donec non enim</a> in turpis pulvinar facilisis. Ut felis.</p>
  <details>
    <summary>Related documents</summary>
    <ul>
      <li><a href="#">Lorem ipsum dolor sit amet,  consectetuer adipiscing elit.</a></li>
      <li><a href="#">Aliquam tincidunt mauris eu  risus.</a></li>
      <li><a href="#">Lorem ipsum dolor sit amet,  consectetuer adipiscing elit.</a></li>
      <li><a href="#">Aliquam tincidunt mauris eu  risus.</a></li>
    </ul>
  </details>
</details>

Example uses

So when could you use <details>? FAQs immediately spring to mind. People often use accordions for FAQs anyway, so they’re a great candidate for <details>.

Also consider a table of contents. It could be a fixed area that scrolls with the content. Something like this perhaps?

You could use <details> to toggle the comments section of a blog, member profiles, details of a download, complex forms, or in web applications as shown in this example from the spec:

In fact, just looking around WordPress as I write, I see plenty of opportunities to use <details>. Let us know your thoughts and ideas in the comments.

Styling

How can we style this thing? Well, to style the disclosure widget itself in WebKit, you can apply some CSS to the pseudo-class ::-webkit-details-marker. You can see a little demo here:

details summary::-webkit-details-marker {
  background: red;
  color: #fff;
  font-size: 500%;
}

We can also position the disclosure widget (to an extent). Here it is floated right. That’s about all we have initially.

So how do we replace the disclosure widget with a custom icon? Using an attribute selector, you can detect whether the <details> element is open or closed and apply an appropriate background image. We do something similar in this example, except that instead of using a background image, we use the :after pseudo-element:

summary::-webkit-details-marker {
  display: none
}
summary:after {
  background: red; 
  border-radius: 5px; 
  content: "+"; 
  color: #fff; 
  float: left; 
  font-size: 1.5em; 
  font-weight: bold; 
  margin: -5px 10px 0 0; 
  padding: 0; 
  text-align: center; 
  width: 20px;
}
details[open] summary:after {
  content: "-";
}

The above example uses literal “+” and “-” characters as the disclosure widget. Depending on your styling, you might need to use :before instead of :after, but both pseudo-elements allow using an image.

The details[open] attribute selector creates some interesting possibilities. And because we’re nice doctors, here’s a more polished example as seen in the screenshot below:

It would be interesting (though not necessarily good design) if you could use CSS transitions to animate the <details> opening and closing, but we can’t just yet.

Accessibility

Unfortunately, at the time of writing, <details> is not accessible via the keyboard. Steve Faulkner writes:

Bottom line is, currently no keyboard support and no usable information exposed to assistive technology.

Try it yourself. If you open a <details> element with your mouse, you can then keyboard through the content, but you should also be able to toggle the details open and shut with the keyboard. So it’s not ideal, but I’m sure the Chrome developers will sort this out soon (won’t you guys?).

Fallbacks

Before anyone exclaims that it doesn’t work in IE6, we know. Thanks to some clever people, we can provide elegant fallbacks though. As listed in this very handy collection of cross-browser polyfills, here are two fallbacks, both of which require jQuery:

• <details> fallback via jQuery by Mathias Bynens
• Another <details> alternative, also based on jQuery by Manuel Bieh

Many of you will be using Modernizr for feature detection, but Modernizr currently doesn’t check for details support. As detailed in the above fallback by Mathias, we can use the following JavaScript:

<script>
  if (!('open' in document.createElement('details'))) {
    alert("No details");
  }
</script>

Why this type of interaction?

Not to look a gift horse in the mouth, but why is this widget in HTML5? Well, like so many other features of HTML5, creating these widgets is just easier with HTML5. Date pickers, sliders, progress indicators, and now accordions can be implemented easily and without JavaScript. Who knows what’s next? Native tabs would be nice :)

Summary

In this article, we’ve demonstrated how to use the <details> and <summary> elements. <details> is a new element and uses the <summary> element to create an interactive disclosure widget natively in the browser.

Currently, <details> only works in Chrome, but hopefully this will change sooner rather than later. There is only one specific CSS trick we can use — ::-webkit-details-marker — but we can use plenty of other CSS to style it up. Let us know in the comments if you’ve got any experience or ideas about the <details> element.

The details and summary elements originally appeared on HTML5 Doctor on August 9, 2011.

<details>
<summary>More information</summary>
<p>Here is the source data that is discussed in the article ... </p>
</details>

This is designed to produce an “expando” box that is closed by default (but can be open by default using the boolean open attribute), only displaying the text specified by the summary as a control. Activating that control opens the whole details element; re-activating closes it again. If no summary text is present, the browser defaults to the rubric “details”. (Added 4 Feb 10:) In browsers that support details, this behaviour does not depend on author scripting, and should work even if JavaScript is disabled or not present.

figcaption lives inside the figure:

<figure>
<img ... > (or video, table etc)
<figcaption>A rabid unicorn goring a fairy.</figcaption>
</figure>

If you want some history, continue reading. Otherwise, bye bye!

Previously, the legend element was specified to do the job of both. Unfortunately, every browser had parsing problems re-using it outside forms. Similar problems were encountered attempting to re-use the caption element outside tables. At Jeremy Keith’s suggestion, the spec then re-used dd and dt, but that breaks too.

Now, two new elements are minted. (I quite fancied one new element – rubric for both, but it’s a pretty esoteric word.)

One of the objections to details, as described by Shelley Powers in her bug to remove it is

the use of JavaScript for the purpose of expanding or collapsing a section is both well-defined and common among web applications. More importantly, following the concept of progressive enhancement, these types of expanding sections are expanded by default if script is turned off. To have a section that is dynamic but not controlled by script is going to cause confusion, particularly among people who turn scripting off and are assuming that there are no “expando” sections in the web page.

In fact, I don’t see how this element will make developing web applications that much simpler. This type of functionality is trivial with JS.

My counter-argument was that an expanding/ collapsing area on the page is a very common requirement. I’ve seen sites pull in a whole JavaScript library just to accomplish this (presumably as the developer was unfamiliar with JS), which bloats the page size for the user. I’ve seen pages where the “details” information is set to display:none by default, and the user cannot expand the information without JS, thereby making the contents inaccessible if JS is not present.

Reinstating this element would be advantageous to developers, who wouldn’t need to learn JS to accomplish a common task; advantageous to users who would get an accessibility bonus from having this behaviour natively in the browser.

While I like to think that the irrefutable logic of my argument, coupled with the tear-jerking rhetorical flourishes in my prose captured both the heart and the head of the editor, I suspect what persuaded him was Apple’s Maciej Stachowiak saying that “the webkit community” were interested in implementing details once the spec was nailed down. Implementation wins the day.

Hello, summary and figcaption elements originally appeared on HTML5 Doctor on February 1, 2010.