Text passage

A text passage, in the RGAA glossary, refers to text present in a page's source code and referenced by another element via aria-labelledby or aria-describedby. It is the mechanism that allows a component to borrow its accessible name (or description) from text located elsewhere in the DOM.

Your close button « × » closes a modal titled « Confirm deletion ». It has no visible text. How do you convey this information to assistive technologies without duplicating the text ? By pointing to the existing title. That is a text passage.

#The mechanism : a bridge between two elements

A text passage relies on a simple principle. An element in the DOM receives an id. Another references it with aria-labelledby or aria-describedby :

<h2 id="modal-title">Confirm deletion</h2>
<button aria-labelledby="modal-title">×</button>

The screen reader announces « Confirm deletion, button ». The button borrows its name from the existing title.

You can reference multiple ids separated by spaces. The browser concatenates the texts in the order specified :

<span id="action">Delete</span>
<span id="object">the file report.pdf</span>
 
<button aria-labelledby="action object">🗑️</button>
<!-- Accessible name: "Delete the file report.pdf" -->

aria-labelledby holds the highest rank in the W3C AccName algorithm. It overrides aria-label, alt, <label>, and the element's text content. Absolute priority.

The RGAA mentions text passages in nearly all its topics : images (criterion 1.1), frames (criterion 2.1), links (criterion 6.1), scripts (criterion 7.1), form fields (criterion 11.1). The wording is always the same : « text passage associated via the WAI-ARIA attribute aria-labelledby ».

#What breaks without warning

A missing id in the DOM. If aria-labelledby points to a non-existent identifier, the accessible name is empty. No error in the console. The component becomes silent.

display: none does not block aria-labelledby. This is counterintuitive. The AccName specification makes an exception : when text is referenced by aria-labelledby, the algorithm traverses display: none and visibility: hidden. Your text passage can be invisible on screen and still provide an accessible name. No other naming mechanism benefits from this exception. A <label> in display: none no longer names its field.

Confusing name and description. aria-labelledby provides the accessible name, the label that the screen reader announces first. aria-describedby provides a supplementary description, read after a pause. Two distinct roles, two attributes not to be mixed up.

#In summary

A text passage is a bridge between two elements in the DOM, built with ids. Verify that your identifiers exist, that the referenced text matches the content expected by the user, and reserve aria-labelledby for cases where native HTML (<label>, text content, alt) is not enough.