<summary>

Overview

The <summary> element, as defined in the HTML Living Standard Specification, is used to provide a summary, caption, or legend for contents inside a <details> element. When clicked, it toggles the state of the parent <details> element, allowing the user to expand or collapse additional information.

Examples and Usage

Using the <summary> and <details> elements, you can create a simple and semantic way to present information that can be expanded and collapsed.

The <summary> element, which should always be the first child of its parent <details>, functions as a clickable interface for toggling additional content. Its content can include heading text, plain text, or any HTML suitable for a paragraph.

Consider a scenario where you're providing information on HTML5 through an FAQ format:

<h2>FAQs</h2>
<details>
    <summary>What is HTML5?</summary>
    <p>HTML5 is the latest evolution of the standard that defines HTML...</p>
</details>
<details>
    <summary>How does HTML5 differ from older versions?</summary>
    <p>HTML5 introduces new elements, attributes, and behaviors...</p>
</details>

In this setup, each <summary> provides a visible heading for the corresponding <details> section. When clicked, the <summary> toggles its parent <details>, revealing or hiding the content inside. This interaction also triggers a toggle event on the <details> element, allowing further customization.

For illustrative purposes, we'll also give a slight visual refinement by applying the following CSS:

details {
    border: 1px solid #ccc;
    padding: 10px;
    margin: 10px;
}
summary {
    font-weight: bold;
    cursor: pointer;
}

This CSS styling frames each <details> section with a border, provides padding to create space inside the frame and sets a margin to separate each section from others. The <summary> text is made bold to emphasize the headings, and a pointer cursor is introduced to clearly indicate the clickable area.

The examples we provided offer a foundational understanding. Some more nuanced insights on browser compatibility and accessibility, along with hints at advanced implementations, can be found in the Accessibility Aspects and Additional Notes sections below.

Attribute Breakdown

The <summary> element doesn't have any specific attributes; it inherits global attributes common to all HTML elements.

Accessibility Aspects

The <summary> element's accessibility considerations are multifaceted, and influenced by various factors.

• Role and ARIA Attributes: Many, but not all, user agents expose the <summary> element with an implicit ARIA role of button. However, no specific role is assigned if the <summary> element is a summary for its parent <details>.

• Global ARIA Attributes: The element can accept global aria-* attributes, including aria-disabled and aria-haspopup. Authors may specify any role and any global aria-* attributes applicable to allowed roles, but it is crucial to consider the context of accessibility in making such changes.

• Exposure to Assistive Technologies: The exposure of <summary> to assistive technologies may vary. Depending on the platform/browser and screen reader pairing, it may be announced differently, such as "button," "summary," or even a "disclosure triangle."

• Styling Impact on Accessibility: Customization of styles, such as removing the default triangle marker, may affect how the state of the widget is communicated in certain browser and screen reader combinations. Care must be taken to ensure that the semantics of the element are maintained.

Associated Elements

• <details>

Additional Notes

• The default style of the <summary> element includes display: list-item, allowing for modification or removal of the default disclosure widget icon (typically a triangle). In Webkit-based browsers like Safari, control over the icon display is possible through the non-standard CSS pseudo-element ::-webkit-details-marker.

• Differences in browser behavior may affect the full functionality of the <summary> element, such as variations in handling the toggle event, exposure to assistive technologies, or the enforcement of rendering rules like automatically placing <summary> as the first child of <details> in the markup.

• Browsers will automatically insert a <summary> element as the first child of a <details> element if not explicitly added, using localized fallback text such as "Details" as the label for the disclosure box.

• Creating custom disclosure widgets using ARIA attributes and JavaScript is an alternative option, allowing more control over the behavior and styling but potentially losing some native browser features like find-in-page functionality. For an example of custom disclosure widgets using ARIA, you can explore this GitHub repository and view the demo page.

Browser Compatibility

For a detailed breakdown of specific browser nuances and older version support refer to the first link in the Useful Resources below.

Useful Resources

Can I use HTML element: summary

The HTML Living Standard Specification: summary

ARIA Authoring Practices Guide on Disclosure Pattern