Skip to content

Name vs Contents

Jump to bottom
Sarah Higley edited this page Oct 23, 2026 · 4 revisions

Background

The ARIA and Accessible Name and Description Computation specifications define when and how web browsers should expose the accessibility "name" of an element to accessibility APIs, and where that information should come from in various situations. Authors often intuit that if they override the name (e.g. via aria-label), they override what screen readers in particular will report to users. Unfortunately, this is not the case, resulting in confusion, frustration and brokenness for users, authors, browser implementers and spec writers. There is no clear guidance on how name and content should interact, and the behaviour is inconsistent across AT.

Name and content are not the same!

The fundamental issue is that name and content are two different things. The name is basically a flat string, even if it is concatenated from the descendants. It contains no semantic or formatting information whatsoever. In contrast, content can contain other elements, semantics and formatting information. When you flatten the content into the "name", you lose all of this information.

Examples:

<a href="foo"><em>bar</em> baz</a>

The name will be exposed as "bar baz", but if we use the name alone, we don't know that "bar" was emphasised.

<a href="foo"><img src="bar.png" alt="bar"> bas</a>

The name is again "bar baz", but we lose the fact that "bar" is an image.

Name and content are not mutually exclusive

There are cases when both the name and the content are important, not one or the other. An example is landmarks.

<section aria-label="Settings">
  <button>Break all the things</button>
</section>

The name of a landmark is important, but you absolutely don't want it to override the content reported to users.

The goal

Ideally, we need documented behaviour which is then consistently implemented across AT. This may require additions to ARIA and Acc Name to properly address specific use cases that are currently ambiguous.

The proposals below are deliberately opinionated in an attempt to provide a solid starting point, but they absolutely need further input and refinement.

Use cases

There are several broad categories of use cases where both name and content might be specified and different.

1. Name provides effective content

Sometimes, the content isn't useful to an AT user. A simple example is an icon button, where there's either no content or the content is a character which is only meaningful visually:

<button aria-label="Close">x</button>

In these cases, the name should always override the content reported to an AT user; the AT should not expose the content. This is unambiguous for certain roles, including button, checkbox, image, link, etc.

The ARIA "Name From: contents" characteristic seems like a useful starting point here. The rule could be that where "Name From: contents" applies, an explicit name should completely override the content reported by AT. Unfortunately, this is problematic for role=row and the various table cell roles; see use case 3 below. It's also problematic for some other cases discussed in the following sub-sections.

Proposed rule: when the name is explicitly provided by the author (Name From: author), the name should always override the content reported to an AT user for roles that fall under the following two categories:

  1. Widget roles that are NOT composite widget container roles or widget roles that allow nested interactives. This includes button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, switch, tab and treeitem.
  2. role="image", as a static role with replaced children.

Open question: How do we express this in the spec? name overrides content: true?

Note that some AT may wish to differentiate between Name From: author and Name From: content in order to implement this rule; e.g. to avoid the loss of semantic and formatting information when the name is computed from content. For AT that need this, this will require an accessibility API mechanism such as the explicit-name IA2 object attribute, which already exists but needs to be documented in the spec.

Open question: Are there existing mechanisms in other APIs that enable differentiating name from author vs. contents?

2. Naming a container

Sometimes, the name is clearly for the container and should always be reported, but it should not impact reporting of the content in any way. Examples include landmarks, grid, listbox and tree. In these cases, the AT should always report the name and provide access to the content.

Proposed rule: AT should always report the name and provide access to the content for roles that fall into the following two categories:

  1. Composite widget container roles such as listbox, tree, grid, or menu. This includes anything in the composite widget roles category in the ARIA spec.
  2. Static containers with name from: author such as main, navigation, or dialog.

The above two categories should roughly correspond to the roles: application, article, banner, combobox, complementary, contentinfo, directory, document, feed, figure, form, grid, group, list, listbox, main, menu, menubar, navigation, radiogroup, region, rowgroup, search, searchbox, sectionfooter, sectionheader, spinbutton, table, tablist, tabpanel, textbox, toolbar, tree and treegrid.

Open question: How do we express this in the spec?

Open question: What about roles blockquote, log, marquee, math, note, status and timer? Why would an author want to explicitly name these and should that override or complement the content? Aren't these more like paragraph, and if so, shouldn't they prohibit naming?

2.1. Named container which can be focused

Some containers, such as roles alert, alertdialog and dialog, might receive focus directly. When this happens, AT should report the name and the content, as well as providing access to the content.

Proposed rule: For roles alert, alertdialog and dialog, when focused authors should be advised to associated the text content using aria-describedby in most cases. AT should report both the name and description. aria-labelledby should not reference the content.

3. Name streamlines the content for efficiency

There are some complex cases where it is useful for an AT to be able to report a streamlined version of the content as a flat string, but where the user should still be able to access the full content inside, including all of its semantics and formatting. However, which one gets reported depends on the context. Examples include social media posts and chat messages. In these cases, a user might wish to quickly navigate through the items (e.g. with the arrow keys), reading the most efficient version of the information. However, they might then wish to inspect more deeply, at which point the semantics and formatting information become relevant. This is perhaps the most controversial and unsupported use case, but it can have a significant impact on a user's efficiency in daily usage.

For example:

<li tabindex="-1" aria-labelledby="user message time">
  <a id="user" href="alice">@Alice</a>
  <a id="time" href="6min">6 minutes ago</a>
  <span id="message">Wow. This blog is horrible: <a href="http://blog.jantrid.net/">http://blog.jantrid.net/</a></span>
  <a href="conv">View conversation</a>
  <button>Reply</button>
</li>

The author has used aria-labelledby to place the message before the time, even though the time actually appears first, because the message is of more immediate interest when skimming.

This use case is currently not really supported by the spec, nor is it consistently supported across AT. One solution could be that AT report the name when the element receives focus, but provide access to the content (ignoring the name) when accessing the element in other ways, such as a screen reader's review cursor.

Currently, NVDA supports this for focusable rows and gridcells. However, a grid isn't always the best fit for this pattern. Focusable articles within a feed is another managed focus widget role that fits within this category. Listitem is also a commonly suggested role here, but listitem isn't meant to be interactive. The interactive lists proposal would officially add it as a widget role supporting flow and interactive descendants.

Proposed rule: AT should report the name when focused, but allow separate inspection of the content, for: widget roles that allow nested interactives and flow content, and any roles that support managed focus and allow nested interactives/flow content.

This currently includes roles gridcell, columnheader, row, rowheader, focusable article within feed, and potentially listitem within an interactive list.

Open question: How do we express this in the spec? Name streamlines content: true? Report name when focused: true? The latter is very AT centric and doesn't quite fit in the spec as it is now.

Another edge case is role="comment", which is currently classified as a document structure role (or container role, to use the terms in this wiki), but in practice frequently has managed focus in apps like Google Docs or Office Online. If we officially updated the comment role to support this usage, it would presumably also fall under this category.

4. Name prohibited

There are some roles for which a name should never be specified and for which AT generally should not report the name. This is included for completeness. These are already specified as name prohibited and no change is proposed or recommended here.

5. What about headings?

Currently, headings can be explicitly named by the author. However, headings often contain interactive controls such as buttons and links which should not be overridden. Various AT have tried to work around this, but it's still rather confusing to users.

The easiest way to solve this would be to prohibit explicit naming on headings, as suggested, discussed, and agreed upon in #1800

Open question: Assuming we still want to support authors focusing the heading as part of a technique used to move the user's cursor within a document, how do we support the heading's content getting announced by screen readers on focus?.

Proposed rule: name from author is prohibited on role heading, but investigate options to specify how to support focusable headings such as allowing name from content but not name from author.

References/prior discussion

1.3 Planning

Tracking issue: FPWD

Clone this wiki locally