This Wiki page is edited by participants of the HTML Accessibility Task Force. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Task Force participants, WAI, or W3C. It may also have some very useful information.

Details element as a replacement for summary attribute, Feb 15, 2010

From HTML accessibility task force Wiki
Jump to: navigation, search

Change Proposal for Details Element as a Replacement for Summary Attribute

NOTE: This document is under active discussion. It is our goal to make a decision at the html-a11y TF telecon on Thursday, Feb 25, 2010. Please also consult the discussion page for this wiki document for more comments and observations on this proposal.


The table element in HTML 4 supported an attribute, summary, which was intended to provide high-level information about the table to users who could not see it. This change proposal suggests replacing the summary attribute of the table element with the details element already in HTML 5. It adds some features to the details element to support use cases unique to table accessibility for users who cannot see. The summary attribute would be allowed to become obsolete, but would remain conforming until a future version of HTML, to allow for backward compatibility with user agents which pre-date HTML 5.


There are several use cases that need to be addressed.

  • Providing information about the content and structure of a table to users who cannot see the table, including some information that will be obvious to users who can see the table, and which might be cause the user interface to become cluttered and less usable for users who can see the table.
  • Providing that information to users who can see the table in an unobtrusive way
  • Providing a mechanism to make that information available to users who cannot see the table, even in situations where for business or usability reasons it is not considered acceptable to have a visable description.
  • Ensuring that developers are aware this information exists, so that they are motivated to create it and keep it up to date


The use case for table description information still exists, but there is a great deal of concern about it continuing to exist in the summary attribute. In general, it is better to put text in elements than in attributes, in order to make it more discoverable for developers and localizers. There is also concern about the fact that summary is not rendered in the visual rendering of the page, and that this causes usability problems for authors and developers, who either don't provide summary text; allow a tool to automatically fill in the summary text, and/or allow the summary text to become stale.

The February 15, 2010 editors draft of HTML 5, makes summary obsolete, and proposes a variety of other mechanisms for captioning and describing tables. However, these proposals do not meet all the use cases important to web authors and designers, business owners of web content, users who can't see, users who have trouble understanding complex data, and mainstream users. In addition, not all of the mechanisms would meet the programmatic determination requirement of WCAG 2.0.

High-Level Modfications

  • Encourage authors to use etails as replacement for summary.
  • Allow details as a child of table or caption
  • Allow for details on a table to be hidden by default, but render a button, outside the table flow, on MouseOver or focus. This addresses the use case of a design that cannot accommodate a text description of the table inline, while still making the description readily available to users and noticeable by authors.
  • Replace the summary child element of details with a button. summary behaves like a button, in that it is a clickable element and triggers an action. In the current spec, this is rendered as clickable text, either provided by the author, or using the default value of "details". In addition, if we are proposing replacing summary with details, it will be very confusing to authors to have the summary element be, not the same value as the old summary, but a button that reveals it.
  • Make summary obsolete but conforming (in other words, deprecated). Authors who need to support non-HTML5 browsers and Assistive Technology would be able to continue to use summary and validate to HTML * This is the same as the current editor's draft, but is a change from previous proposals on this topic.

Spec Changes

  • To 4.11.1 The Details Element
    1. Content model: One summary button element followed by flow content.
    2. Add under attributes attribute boolean noflow;
    3. Replace description of summary element, with the following:
      The first button element child of the element, if any, creates a button that will toggle the details element open and closed. If there is no child button element, the user agent SHOULD render a small button which matches the user interface of the user agent, indicating that this is an expandable area. For example, an arrow graphic on a GUI user agent, or a text link on text-based user agent. On user agents that support an accessibility API, the accessible name of this button MUST be a localized string indicating the function of the button (e.g. "details" or "more info").
    4. After the open attribute, add the following:

      The noflow content attribute is a boolean attribute. If present, it indicates that the details section, including its button, are placed outside the flow of the content, and that neither is rendered by default. The button is focusable, and when a user navigates to it in the focus order, it becomes visible. The button also becomes visible when the user hovers over parent of details. The button, once visible behaves as specified above, toggling the open state of the details.

      If the noflow attribute is present, the button and details elements MUST NOT be rendered by default; MUST render on hover and focus; and MUST render outside the flow of the page. When the attribute is removed, then the button and details must render in the flow.

      NOTE: I don't really like the name noflow, and am open to other ideas. The behavior is very different than hidden, so we can't use that. (comment from Cynthia Shelly) Suggestions, so far, include: "discoverable" (comment from Gregory J. Rosmaita)

      The noflow attribute must reflect the noflow content attribute.
    5. in the examples, replace all instances of summary with button
    6. Add an example:
       <details noflow>
        <p>Text describing the table</p>
      .... table stuff ....

      In this example, the button would not be visible when the page was initially rendered. If the user hovers over the table, the default button would appear floating above the table in the z-order, clicking the button would open the details, also floating above the table in the z-order. Clicking it again would toggle the details closed. Moving the mouse away from the table would hide the button.

      The button would exist in the focus navigation (sometimes called "tab order"), following normal rules. When the button receives focus, it would appear floating above the table in the z-order. Activating the button (for example, by hitting the "ENTER" key) would open the details, also floating above the table in the z-order. Activating it again would close them. Moving focus off the button would cause it to become invisible.

      See the table section for more on details and its uses for table accessibility.

  • Remove section 4.11.2 The Summary Element (this is now covered by the button element in 4.10.6)
  • In Section 4.9.1 The table Element
    1. Under Content Model:
      In this order: optionally a caption element, followed optionally by a details element followed by either zero or more colgroup elements, followed optionally by a thead element, followed optionally by a tfoot element, followed by either zero or more tbody elements or one or more tr elements, followed optionally by a tfoot element (but there can only be one tfoot element child in total).
    2. Remove text from "For tables that consist of more than just a grid of cells with headers in the first row" to "may not be useful to everyone, but it might also not be useful to users who can quickly navigate the table with an accessibility tool"
    3. Add the following text:
      Authors MUST describe tables for users who cannot see them, to provide information that is obvious to visual users of the table, but would be difficult to determine by navigating the table cell by cell in an auditory user agent, and which cannot be derived by the user agent from the markup. Table descriptions should provide enough information to allow the user to decide if he needs to explore the table, which can be time-consuming for users with non-visual user agents. The description should include any information that is obvious from the visual structure of the table, and highlight trends or other conclusions that the author expects the user to draw from the table. For more information on table descriptions, see The National Braille Association's Tape Recording Manual, 3rd edition (originally copyrighted in 1971). Excerpts are available from the w3c at <>

      Some tables are complex enough that all users would benefit from such descriptions. In those cases, authors SHOULD make the description available to all users.

      There are three ways to provide these table descriptions:

      Using the details element

      The details element provides for a small button, either graphical or text, which toggles a text area. This hides the description where it will be unobtrusive to users who can see the table, but available should they wish to view it. The description text will be easily noticed by authors and testers.

      Add example 1 from file:

      When a table has a child details element, user agents which support an Accessibility API MUST map the text of the details to the description property of that API. For tables with details but no caption, user agents MUST map details text to both name and description.

      Using the details element with a @noflow attribute

      In cases where, for business or design reasons, it is not acceptable to have a visible button or text description on the page, authors MAY use the noflow attribute to hide the details UI until it is focused or hovered.

      When the noflow attribute is present on the details element, the element is outside the HTML flow, and sits at the top-most z-order on the page. It not visible when the page is initially displayed. The button is focusable, and appears in the focus navigation (that is, the "tab order") following normal rules. When the button receives focus, it becomes visible. When it loses focus it becomes invisible. The button also appears when the table is hovered. Activating the details button toggles the details text, also outside the flow of the page.

      Add example 2 from file: <>

      Using the aria-described-by attribute to point to text elsewhere on the page

      If the table is described in other text on the page, as is common in formal documents, use the aria-described-by attribute to link the table to the surrounding description in a way that is programmatically determinable for assistive technology.

      Add example 3 from file: <>

  • Change:
    If a table element has a summary attribute, the user agent may report the contents of that attribute to the user.


    The summary attribute is retained for backward compatibility to earlier versions of HTML. If authors use summary, they SHOULD provide the same type of description as would be used in a table details element (link?). If it is present, user agents that support Accessibility APIs SHOULD map it to the description property of that API, and to the name property when there is no caption. In tables where both summary and details are present, user agents MUST map details rather than summary.
  • Add a sub-section of 4.9 with the following text

    Guidance for Conformance Checkers

    A table which includes a summary attribute: The advisory SHOULD encourage the author to use details instead, except where summary is needed for backwards compatibility.


Positive Effects

  • The "display on focus or hover" feature for the details element provides for a common UI feature directly in HTML, without requiring authors to create it.
  • Using button instead of summary for the trigger of details has advantages. The behavior of the element is that of a button, so no additional element is needed. It also removes a possible point of confusion between the HTML 4 attribute summary, and the HTML 5 element summary;
  • Authors would have a mechanism for providing to non-visual users the information that is difficult for them to glean by navigating around the table.
  • The table information can be hidden by default, with or without an obvious button to show it, or linked to another part of the document.
  • Even when the table information is hidden and the button is not visible at first, it will show up when the table is hovered. This increases its visibility to authors and testers, and will help to ensure that they will make this information both accurate and up to date.
  • HTML and WCAG will not be giving contradictory advice.
  • summary can be made obsolete, and replaced by something better.

Negative Effects

  • None I can think of.

Conformance Classes Changes



  • There is some concern that regulations which reference summary will become out of date. This is mitigated to some extent, both by keeping summary as obsolete but conforming, and by providing a clear migration path from summary to details.