HTML < details > Element by Jess and Sophie

Introduction

According to MDN Web Docs, “The <details> tag is a disclosure widget in which information is visible only when the widget is toggled into an “open” state. A disclosure widget is typically presented onscreen using a triangle that rotates (or twists) to indicate open/closed status with a label next to the triangle.” In other words, the <details> tag is a feature that allows information to be shown or hidden depending on how the user wants to view the page. This article will describe the different ways in which the developer can create, style and use this tool.

The <summary> Tag

For the <details> element to be activated, its child element, the <summary> tag, is required. According to MDN Web Docs, “The <summary> element is necessary for the widget to appear so the hidden description can be toggled open or closed. It can only be used as the first child of the <details> element. When the <summary> element is clicked, this event is sent to the <details> element. This is what’s called a “toggle event”.” Because of the <summary> element, we are now capable of creating this effect in HTML rather than making an event in JavaScript. The <summary> presents as a heading for each <details> element, and is what is clicked on, along with the widget, to reveal or close the information hidden underneath.

The details element can be utilised in one of two ways: open or closed. When the developer uses a closed details tag this causes the information below the <summary> element to be hidden when the user first enters the page. This can be useful when the developer doesn’t want to overwhelm the user with too much content, and allows the user to choose whether they want or need to view the hidden information. When the <details> element is open, it presents in HTML as <details open>. This causes the information underneath to be shown when the user first enters the page. The user can then choose whether they would like to toggle the element closed or keep it open.

Image of how the HTML is presented on the website

Styling the Widget

Due to the <summary> tag a widget will appear next to the heading. The default shape of the widget is a triangle. The triangle will change direction depending on whether the information is open or closed. If the information is open the triangle will point down, and if the information is hidden the triangle will point towards the heading. This widget has the ability to be customised in CSS to change it to different shapes. The <summary> element supports the list-style properties, like list-style-type, so you can change the disclosure triangle to one of the available options given to you in CSS, such as a square, a circle, etc. You can also use list-style-image to change it to an image of your choice as well. The last way the widget can be styled is to remove it completely by using list-style: none.

If the choice is made to change the shape of the widget to anything other than a triangle you need to ensure that the user knows that the <summary> heading is clickable. This is because the triangle is the only shape that provides a clear indication that the element has been toggled, and an image will not move. You can achieve this effect in CSS by adding curser: pointer in the details summary section. This will cause the curser to change to the shape of a pointer finger and notify the user of a clickable element.

According to Scott O’Hara from an article written in 2022, “If removing this marker so you can insert your own custom chevron or other visual expanded/collapsed state marker, it will actually make the state of the widget unclear with Firefox and VoiceOver, since the announcement of the default triangle direction is the only way state is communicated in that pairing. Other browsers also have an issue with consistently announcing the toggled state of the disclosure widget if this marker is removed. Something to keep in mind as you determine just how important it is to restyle an element whose semantics are, at least presently, semi-reliant on their default styling.” Browsers tend to have a difficult time understanding and announcing widget shapes other than the default triangle, making it difficult for those visually impaired or those that use screen readers to know it’s a clickable element, so is strongly advised to keep the triangle widget unless it is absolutely necessary for you to change it.

CSS showing the styling of the disclosure widget

Image showing how that styling displays on the website with the image of the arrow

Styling the <details> Element

If you want to contain your collapsible content you can use the border property to style both the summary and paragraph elements together. By putting the elements in a box it enables the content to be separated and kept clear. This may be depending on the content.

Browser Compatibility

Currently both the <details> and the <summary> elements have full support on the latest version of each browser. Although the <summary> tag is read as a button therefore it strips the roles of any other child elements for those that use assistive technologies such as screen readers. For example, if you put an h4 in the <summary> tag it would not be read by the assistive technology as a heading.

It is possible to create a list within the <details> element but be aware that it is not supported by some web browsers. These browsers include Safari and Safari iOS, Opera Android and WebView Android.

Real World Uses

Please see below examples of where to find uses of the <details> element used in real world scenarios:

FAQ’s
Navigation
Condensed info

Conclusion

To conclude the <details> element is a great tool to reduce clutter on a web page. It is an innovative advancement in HTML for the web design world that reduces the need for JavaScript.