LearnHow to Use the Details and Summary Elements in HTML5

A number of new interactive elements were introduced with HTML5 that provide native implementations of common UI widgets like dialogs and modals. Among these new additions are the <details> and <summary> elements. These elements allow developers to create collapsable UI widgets the user can click to show or hide content.

In this post, we’ll take a deep dive into the <details> and <summary> elements. You’re going to learn how to use these elements in your HTML markup, how to apply custom styling to them, and what browsers they work in.

Let’s get started.

Using the Details and Summary Elements

The <details> and <summary> elements are used in combination to create a UI widget that allows the user to find out more information about a topic by clicking on a summary.

The <details> element is responsible for marking up all of the content relevant to the particular topic. The <summary> element is used to specify a short piece of text that describes the rest of the content in the <details> element.

<details>
    <summary>Summary text</summary>
    Content goes here...
</details>

By default, the browser will only display the content within the <summary> element to the user. Once this summary is clicked, the remaining content will become visible.

The browser will use the text from the first <summary> element within the <details> element when constructing the widget. If no <summary> element is specified, the browser will simply display “Details.”

If you’d like the widget to be open when the page loads, you can specify the open attribute on your <details> element.

<details open>...</details>

The browser will toggle the open attribute for you as the user opens and closes the widget.

So what kind of content should you be using the <details> and <summary> elements for? Simply, any additional information you’d like to provide about a subject. For example, you could use these elements for marking up order data within an e-commerce app. In the following example, the user is presented with an order number that, when clicked, will reveal the full information about the order.

View The CodePen Demo

<details>
    <summary>Order #24892105</summary>
    <table>
        <tr>
            <th scope="row">Order Date</th>
            <td>30th May 2003</td>
        </tr>
        <tr>
            <th scope="row">Order Number</th>
            <td>#24892105</td>
        </tr>
        <tr>
            <th scope="row">Courier</th>
            <td>Buy N Large Postal</td>
        </tr>
        <tr>
            <th scope="row">Shipping Address</th>
            <td>
                P. Sherman,<br>
                42 Wallaby Way,<br>
                Sydney,<br>
                Australia
            </td>
        </tr>
        <tr>
            <th scope="row">Billing Address</th>
            <td>
                P. Sherman,<br>
                42 Wallaby Way,<br>
                Sydney,<br>
                Australia
            </td>
        </tr>
    </table>
</details>

You could also create a UI widget that presents additional controls when a user clicks on a key object in your application.

View The CodePen Demo

<details>
    <summary>README.txt</summary>
    <ul>
        <li><a href="#">Open</a></li>
        <li><a href="#">Edit</a></li>
        <li><a href="#">Duplicate</a></li>
        <li><a href="#">Delete</a></li>
    </ul>
</details>

Other applications could include things like questions and answers within FAQ pages, tables of contents, and collapsable fieldsets for multi-part forms.

Styling Details and Summary Elements with CSS

Now that you have an understanding of how to use the <details> and <summary> elements in your HTML, let’s take a look at how you can style these elements using CSS.

Targeting the details element in your CSS allows you to style all of the content within the element.

details {
    /* Your styling rules. */    
}

If you want to style just the area that opens and closes the widget, you should target the summary element.

summary {
    /* Your styling rules. */    
}

Targeting these elements directly like this will add styling rules that apply in both the open and closed states of the widget. If you want to style the widget differently when it’s open or closed, you can use a CSS selector that only applies to <details> elements with the open attribute.

/* Open details element. */
details[open] {

}

/* Summary within an open details element. */
details[open] summary {

}

By default, the browser will display a small marker triangle to the left of the summary text that indicates the current state of the <details> element. You can target this marker in CSS using the -webkit-details-marker pseudo-class.

/* Change the color and size of the marker. */
summary::-webkit-details-marker {
    color: #69c773;
    font-size: 200%;
}

You can even hide the marker completely by setting its display property to none.

/* Hide the marker completely. */
summary::-webkit-details-marker {
    display: none;
}

If you want to use your own marker icon, start by hiding the default marker (as shown above), and then use the :before pseudo-element to add your custom icon. This should be applied to the summary element.

View The CodePen Demo

Here’s the CSS code used to create the example above.

details {
    border-radius: 3px;
    background: #EEE;
}

details summary {
    font-size: 17px;
    vertical-align: top;
    background: #333;
    color: #FFF;
    border-radius: 3px;
    padding: 5px 10px;
    outline: none;
}

details[open] summary {
    background: #69c773;
    color: #333;
}

/* Hide the default marker. */    
details summary::-webkit-details-marker {
    display: none;
}

/* Add the custom marker in the default state. */    
details summary:before {
    display: inline-block;
    width: 18px;
    height: 18px;
    margin-right: 8px;
    content: "";
    background-image: url(https://s3-us-west-2.amazonaws.com/s.cdpn.io/4621/treehouse-icon-sprite.png);
    background-repeat: no-repeat;
    background-position: 0 0;
}

/* Move the sprite image when the details box is open. */
details[open] summary:before {
    background-position: -18px 0;
}

In this code, I’m using the :before pseudo-element to add the initial marker icon. I then create another rule that alters the positioning of the background image (so as to change the visible section of the sprite) when the details element has an open attribute.

Browser Support for the Details and Summary Elements

Browser support for the <details> and <summary> elements still isn’t great. Chrome, Safari, and Opera all support these elements, but Internet Explorer and Firefox do not.

IE	Firefox	Chrome	Safari	Opera
–	–	12.0+	6.0+	15.0+

Source: http://caniuse.com/#feat=details

There are a number of polyfills available that will add support for the <details> and <summary> elements to other browsers. Two of the best ones that I’ve found are:

• Element.details by Егор Халимоненко
• Details Polyfill by Manuel Bieh

Final Thoughts on Details and Summary Elements

In this blog post you’ve learned how to use the <details> and <summary> elements to create your own collapsable UI widgets. You’ve also learned how to style these elements with CSS, as well as how to replace the default marker icon with your own images.

It’s really encouraging to see browser vendors creating native implementations for some of the most commonly used UI widgets. What other UI components would you like to see added to browsers in the future?

Useful Links

• W3C HTML5 Specification: Interactive Elements
• WHATWG HTML Living Standard: Interactive Elements
• Modernizr HTML5 Cross-Browser Polyfills

• code
• css3
• details
• html
• html and xhtml
• html5
• summary