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.

We also want to know what areas of HTML5 you’d like us to cover in future articles, so let us know!

Older browsers and XHTML

Brett Prichard asked:

If I were to use one of the new tags in HTML5, (i.e., <video> or <header>) what would happen when the page is rendered by an older browser?

The other question I have is will there be an XHTML equivalent? XHTML 2.0 breaks off compatibility with HTMLs 1-4, but will it be compatible with HTML5? I prefer to code in XHTML.

Thank you for reading.

To answer your first question: nothing special. The content nested within the element is displayed. (In the case of video, the fallback content is shown.)

Regarding your second question, I wrote about the XHTML serialisation of HTML5 a while ago.

— Thanks, Bruce

ARIA

Joseph Chapman asked:

My colleagues and I wish to switch our doctype to the streamlined <!doctype html> and implement several things we learnt from Jeremy Keith last Wednesday, primarily ARIA.

We know that support is good as long as we add an extra DTD, but we can’t find the appropriate doctype declaration to stick on the end of ...html> Any ideas? We are really keen to kick this off and use a new piece of technology that will help springboard our site to a new level of accessibility.

Any answers appreciated.

Thanks for your help.

It’s okay to add ARIA to HTML5 now without using a different doctype. I suggest you give this part of the spec a read.

I believe a task force has been created to more closely align ARIA to HTML5. We plan to cover ARIA more in a future post.

Hope this helps

— Rich

Attribute Minification

Nick Leon asked:

Hey there HTML5Doctor,

I consider myself a strong POSH developer. One of the requirements for valid XHTML is that “attribute minimization” is not allowed. HTML permits “attribute minimization”, where boolean attributes can have their value omitted entirely, e.g., <option selected>. All XML attributes must have explicit quoted values, so in XML this would be written as <option selected="selected">.

I was wondering where HTML5 stands with attribute minimization. I noticed in some of your example code, you provided the minimized form of the attribute, e.g., <audio src="elvis.ogg" controls autobuffer></audio>. Is this valid in HTML5? Would this be the valid version for XHTML5:

<audio src="elvis.ogg" controls="1" autobuffer="0"></audio>?

Those are both valid HTML5 structures (however, controls=”1″ isn’t legal; you need to say controls=”controls”).

In HTML5, you can format attributes as you please. In XHTML5 (the XML serialisation), you need to obey the XML rules.

— Cheers, Bruce

Offline storage

Kevin Searle asked:

I’m having a hard time wrapping my head around the offline storage capabilities of the HTML 5 spec. Can you consider an “HTML 5 Offline Storage 101″ article?

Just to clarify, do you mean “storage” or “offline”? They’re two very different things.

Storage relates to variables, like cookie jars but a lot bigger.

Offline applications are about detecting connectivity and possibly running your app without a connection to the Web.

We (i.e., Remy) will be writing about both of these topics, but it’s useful to know which is more in demand than the other.

In the meantime, feel free to check out the demos I’ve written at HTML5 Demos (covering offline, storage, and web databases).

— Remy

Nav Title (in the document outline)

D Ross asked:

Working on my new site and checked it with the outliner. I’m getting an “untitled section” showing up because I don’t have a headline inside my “nav” element.

Is this correct? Do I really need to title my main nav?

If so, is adding an <h5> or something similar with the words “main navigation” good enough? If so, is hiding it with display: none okay?

Thanks,

DRoss

Yes, “untitled section” is fine. I know it’s been suggested to the developer of the outliner that it should say “navigation” or something similar, but I’m not sure when or whether that will happen. (You’ll see the same thing with <aside> too if there’s no heading nested directly beneath the element).

Thanks,

— Rich

The details element

Bart asked:

Hello Doctors!

I’d like to ask you a little help with understanding the “details” element.

As the W3 spec says: “The details element represents a disclosure widget from which the user can obtain additional information or controls”.

I’m not sure if I get it right, but I think I can use this element to put details about a post (such as date and time) and controls, including “answer”, “save” and “repost”.

Please tell me if I’m wrong.

Regards, Bart

PS. I love the HTML5doctor blog, it’s so important to explain how to use HTML5. Keep up the great work!

This question triggered a flurry of responses from several of us doctors, so we’ve added them all here for you.

Answer 1

The spec says <details> is not appropriate for footnotes, and you could argue that post details are footnotes. Also, the <details> element has the option to show or hide its content, which suggests to me that it’s not appropriate for the post details.

You could possibly use a <section> or a <footer> for the post details, but I’m not clear on what you mean by “controls”.

For the date/time, you can use the <time> element:

<time class="published updated" datetime="2009-09-23">September 23rd, 2009</time>

Other doctors might have other opinions, but I hope this helps.

— Tom

Answer 2

Just to follow up on Tom’s reply: the user viewing your content can control whether or not they see the details.

The <details> element is an interactive element that is collapsed by default, so that only the heading is visible. The heading should be marked up in a <dt> element (if absent, it will read “Details”).

The control that the user agent should render (when fully supporting the <details> element) is a small triangular button to the left that, when clicked, toggles the visibility of the element’s contents.

If the <details> element should be open by default, it should have its open attribute set.

I would use <details> for any content that still allows the surrounding content to make sense while not necessarily needing to be seen. So in your example, I would put the metadata in the <details>, but not the “user controls” to reply, save, etc., since the user should always be able to see that they can perform these actions.

While the browser vendors haven’t implemented the interactive aspect of details, I, for one, will be emulating this using JavaScript.

I hope that helps (too!).

— Remy

Answer 3

You can also use pubdate as an attribute of <time>:

<time pubdate datetime="2009-09-23">September 23rd, 2009</time>

pubdate is useful when you have two different times in the post. For example, for a future event:

<article>
<header>
<h1>Gig: Hixie and the Pixies, <time datetime="2010-01-01">Jan 1st 2010</time>, Royal Albert Hall</h1>
<p>Published <time datetime="2009-09-21" pubdate>Sept 21, 2009</time></p>
</header>
<p>With Lachy on kazoo, Henri on Sousaphone, Pilgers on the triangle, and Hixie conducting</p>
</article>

I feel a post about the <time> element coming on…

— Bruce

More to come

That wraps up this round of questions! We’d like to know what areas of HTML5 you’d like us to cover in future articles, so leave a comment below or send us an e-mail.

Your Questions Answered #4 originally appeared on HTML5 Doctor on December 9, 2009.

Although not immediately obvious why it’s the right choice, it appeared to work for our needs…at first. Of course now, it’s been discovered that it’s actually a pretty bad idea.

How we got here

In short, details and figure solve a common design pattern and provide nice new semantic tags to solve that problem. A figure could be an image you’re referring to in an article or chapter of a book, and the details element allows the user to interactively show and hide the details of some piece of information.

Both elements can contain a heading element to label up the contents. For some reason, beyond this author’s understanding, these two elements, completely different in meaning, have been historically tied to using the same solution solve the problem how to markup the heading.

As I mentioned earlier, originally the proposed solution for the headings was to use the legend element, which proved to completely break in every browser (in new and interesting ways).

Skip forward to mid-September, and Jeremy Keith proposes that we solve the legend issue with the dt/dd combo, and Ian Hickson says:

That’s not a bad idea actually. Ok, done.

Before this was proposed there was lots of discussion about why we couldn’t introduce a new element to solve this problem, and Ian points out already 18 (or 22, I forget!) elements that represent some sort of heading. This is the argument for not introducing another new heading type element to solve the details and figure problem.

The problem with dt/dd

Ironically the problem isn’t with the dt part of the solution, it’s actually with the dd.

Dean Edwards (genius behind some very cool JavaScript and something that will soon blow your minds) has been testing these elements in detail and found a very serious issue with the dd in, guess what, IE6 & 7. I want to explain and draw attention to what Dean has found.

Styling a dd within details or figure (and probably other elements) bleeds to the next element.

By styling a dd red, and only the dd, here’s what it should look like (and does in IE8):

Where as in IE7 (and IE6), the red style bleeds in to the following p element (note the “this paragraph shouldn’t be red”):

![dd styled in IE7](

What’s more, if you look back at the screen shots you can see the last paragraph says “Contents of first <dd>”. The result of that test is being generated by the following JavaScript:

document.getElementsByTagName('dd')[0].innerHTML

Notice how in IE7, the contents of the first dd‘s innerHTML is empty.

The problem here is that:

1. IE7 and below can’t style a dd properly without it breaking and the style bleeding in to adjacent elements.
2. JavaScript, randomly, can’t see the contents of the dd.

Is there hope?

There is a hack that fixes this issue. It’s pretty mad, but it does fix the styling issue. However the side effects from this hack are outright unacceptable and are so serious I would argue that the hack solution itself is a bug.

The hack is over at the public-html of W3.org, and involves stuffing an open object tag just before we close the head tag.

This isn’t a clean solution for including in HTML by hand, authors won’t remember or might get it wrong, so it needs to be perhaps automated as part of the HTML5 enabling script, right? It would have to be inserted using document.write() as the last part of the head element.

Dean went on to test this, and he found:

There is a nasty side effect though. As you mentioned the document.write() should be the last thing in the <head>. If there are any scripts following the document.write() then they are not executed.

The really freakin’ important bit:

If there are any scripts following the document.write() then they are not executed

So, to answer the question: is there hope? No, not for the dd/dt combo. It can’t be styled properly and hacks will break JavaScript.

We want the details

We, as authors, want to make use of details and figure today. Waiting for IE7 to fall out of circulation before we start using these elements (as it’s been proposed a number of times on the IRC channel and mailing boards) is outright not going to happen. IE6 & 7 are going to be around for a good more number of years, certainly IE7 (IE6 has at least another 5 years in the beast).

We are going to start enabling the details interactive UI pattern using JavaScript whilst we wait for vendors bake it in to the browser, so the final proposed markup needs to work in all the browsers, including IE6 and IE7.

What are our current options?

1. Give new meaning to an existing element (as we’ve already tried to), legend, label and dt/dd have been tried, tested and failed. What else could we use?
2. Repurpose one of the existing new elements (keeping in mind that the dt/dd was repurposed so it should be a consideration).
3. Create another heading element to solve this problem.

The problem is that the conversation seems to have lost steam (or certain Dean was starting to see the conversation go in circles). If you want to see these two elements make it the final spec, and correctly, head over to either the IRC channel or the mailing list, and get heard.

Reference links

• Dean’s original details test (my modified tests to fire the innerHTML on load: details, figure)
• Litmusapp browser screenshots of the results: details, figure
• whatwg mailing list thread: September, October

  Related Posts:

  • Legend not such a legend anymore
  • Hello, summary and figcaption elements
  • How to get HTML5 working in IE and Firefox 2
  • September HTML5 spec changes
  • 2022, or when will HTML 5 be ready?

dd-details wrong again originally appeared on HTML5 Doctor on October 12, 2009.

However I ran in to some very serious issues with the tag, so serious, in it’s current state, it’s unusable.

Overview of the details element

The details element, by default, is a collapsed element whose summary, or label, is the first child legend (if no legend is used, the UA provides a default, such as “Details”), with a triangular button to indicate it’s current open state.

If you include the open attribute, then the element is open by default. In theory, you could attach a click event to the legend, and switch the open attribute.

The markup would roughly be this:

<details open="open">
  <legend>Terms & Conditions</legend>
  <p>You agree to xyz, etc.</p>
</details>

Here’s the details test page I was working from: HTML 5 details test

The issues

The biggest problem, and the show stopper for me, is that the browser’s treatment of the legend element completely breaks this markup pattern – this is true for all the major browsers: Opera, Safari, Firefox and IE (tested in all the latest and some older browsers). I’ll go in these issues in detail in a moment.

Other problems include:

• Styling the legend element is exceptionally difficult, particularly positioning
• Using the WHATWG guidelines to styling the details element prove both difficult to interpret and difficult to implement.
• When using CSS to style the open state of the details element using: details[open] { height: auto; }, meant that once I changed the open state using JavaScript, it wouldn’t trigger the browser to redraw (as it would if I had added a class). I’ve run in to this before, CSS 2.1 is styling source, not the DOM.

Legend treatment

Surprisingly Firefox is the worst one out in these issues, the rest of the browsers have fairly same treatment of the issue. In the screenshots, I’ve included a fieldset and nested legend for reference.

Internet Explorer

IE7 & IE8 closes the legend element it encounters when it’s not inside a fieldset element and move it’s contents out to an adjacent text node.

What’s also strange, is that looking at the DOM it also creates another empty(?) closed legend element after that text node. It doesn’t have any effect, but just looked odd:

Opera

Opera (9 & 10b) is very similar to IE in it’s treatment of the legend in the details element, except it doesn’t create the second closing legend node. It just closes the legend, and creates the adjacent text node.

Safari

Safari simply strips the legend all together out of the DOM. So much so, that if you open the web inspector, then the error console, you’ll see it warning out that it’s encountered an illegal element, ignoring it, then encountering the closing tag, so it ignores that too. You’re left with just the text node.

Firefox

The best for last. Firefox goes one step beyond the other browsers. It assumes you’ve forgotten to include the fieldset element. So when it hits the legend element, Firefox inserts an opening fieldset up until it finds (I believe) the closing fieldset element, which obviously it doesn’t so the result is the rest of the DOM, after the first illegally placed legend ends up eaten by fieldset element, which leaves my DOM in a mess:

Impact on other elements

details isn’t the only element that reuses the legend element for labelling, the figure element also is supposed to support the legend element. The result is obviously going to be the same.

Conclusion

We can’t style the legend element when the text is being thrown out by all the browsers, and Firefox’s DOM mangling is just too painful to look at.

This basically means that we can’t, in any reasonable amount of time, use the legend element inside both the details and figure element in the spec’s current state.

For me, I’ll be using an alternative element, probably just a p element styled to look like a legend, but that’s really not the point. Ideas anyone?

It turns out we weren’t the only ones looking at this and Ian Hickson has responded on the issue:

My plan here is to continue to wait for a while longer to see if the parsing issues can get ironed out (the HTML5 parser in Gecko for instance solves this problem for Firefox). If we really can’t get past this, we’ll have to introduce a new element, but I’m trying to avoid going there.

It’s fine to think that Gecko will update, but it’s IE that I’m worried about, they won’t turn out their render engine, and the result is we’ll have to avoid using the legend in any element other than fieldset.

Legend not such a legend anymore originally appeared on HTML5 Doctor on July 31, 2009.