Disclosure Widget (<details>, <summary>)

When To Use

• To design a widget that provides the option to either conceal (collapse) or reveal (expand) content. ³

Rules

• There is no consensus about whether or not to use the semantic <details> and <summary> elements or to create this functionality without those elements.
• Disadvantages of using <detail> and <summary> for disclosure widgets: 
  • It is worth noting that the <details> and <summary> elements may be interpreted differently by various screen readers, resulting in inconsistent accessibility experiences (e.g. completely different way of announcing those elements). But don‘t try to create custom announcements by for example changing ARIA roles. This is almost always a bad idea. Alternatively, implementing the functionality without these elements could potentially lead to a more consistent user experience that is under your control. ⁴
  • The <details> and <summary> elements can have bugs, including missing state change announcements, that may affect accessibility. ⁴
  • It is important to note that the <details> and <summary> elements are not supported on Internet Explorer. Whether or not this presents a problem depends on your user base and their preferred web browser. ⁵
• Advantages of using <detail> and <summary> for disclosure widgets:
  • One advantage of using the <details> and <summary> elements is that they are semantic, meaning that they provide additional meaning and structure to your HTML code.
  • Using the <details> and <summary> elements can also offer more features out of the box than a custom implementation. ⁴
  • It‘s important to note that creating a custom implementation may increase the likelihood of mistakes being made, such as hard coding and not updating aria states in the HTML if the JS is removed. ⁴
  • Chromium Browsers will include and expand the content when you use the browser search functionality. Although this behavior might not be suitable for all use-cases, like tabs. ⁷
• W3C APG disclosure widget pattern examples does not use the <details> and <summary> elements. This is a great resource to start, when implementing this widget an your own.
• When utilizing the <summary> element:
  • it is important to avoid placing semantic tags such as headings within it. This is because the <summary> element has an implicit ARIA role of button, which removes all roles from child elements. Alternatively, you can enclose the <summary> element inside a heading to preserve its semantic meaning. ²
  • hide the default triangle by using this CSS below. If you would do it another way you would risk changing the announcements made by assistive technologies. When you then insert your own custom indicator graphic make sure to use aria-hidden=“true” on on it, since it does not convey any additional information. ⁴
• Implementing a custom disclosure widget is fairly straight forward. An example can be found in the source of this sentence. ⁴
  • Its best practice to don‘t hard code any attributes that will get changed by JavaScript in the HTML itself but to create and update these attributes entirely in JavaScript and to also hardcode the widget in its open state. This is also called progressive enhancement. That way people who don‘t run JavaScript on your site (e.g. reading modes) still can use the widget. ⁴

summary::-webkit-details-marker {
    display: none;
}

summary {
    list-style: none;
}

Sources 

1. MDN: <details>: The Details disclosure element by Mozilla contributors is licensed under CC-BY-SA 2.5
2. MDN: <summary>: The Disclosure Summary element by Mozilla contributors is licensed under CC-BY-SA 2.5
3. Disclosure (Show/Hide) Pattern by W3C WAI Tutorial Contributors is licensed under W3C Document License
4. Scott Ohara: The details and summary elements, again by Scott Ohara
5. Hassell Inclusion: Accessible accordions part 2 – using <details> and <summary> by Graham Armfield is licensed under Creative Commons Attribution 4.0 International License
6. HTML Spec: Living Standard, 4.11 Interactive elements, details is licensed under Creative Commons Attribution 4.0 International License
7. Adrian Roselli: Details / Summary Are Not [insert control here] by Adrian Roselli © Adrian Roselli