ARIA9: Using aria-labelledby to concatenate a label from several text nodes

Important Information about Techniques

See Understanding Techniques for WCAG Success Criteria for important information about the usage of these informative techniques and how they relate to the normative WCAG 2.0 success criteria. The Applicability section explains the scope of the technique, and the presence of techniques for a specific technology does not imply that the technology can be used in all situations to create content that meets WCAG 2.0.

User Agent and Assistive Technology Support Notes

Description

The aria-labelledby property can be used to label all visual objects. Applied to inputs, the aria-labelledby property can be used to label native inputs as well as non-native elements, such as custom text inputs constructed with div contenteditable="true".

One particular use of aria-labelledby is for text inputs in situations where a meaningful label should consist of more than one label string.

Authors assign unique ids to the label strings to be concatenated as the label for the input element. The value of the aria-labelledby attribute is then a space-separated list of all ids in the order in which the label strings referenced should be read by screen readers. Supporting user agents will concatenate the label strings referenced and read them as one continuous label of the input.

The concatenation of label strings can be useful for different reasons. In example 1, an input is nested within the context of a full sentence. The desired screen reader output is "Extend time-out to [ 20 ] minutes - edit with autocomplete, selected 20". Since the id of the text input is included in the string of ids referenced by aria-labelledby, the value of the input is included in the concatenated label at the right position.

Another application of aria-labelledby is when there is no space to provide a visible label next to the input, or when using native labels would create unnecessary redundancy. Here, the use aria-labelledby makes it possible to associate visible elements on the page as label for such inputs. This is demonstrated in example 2 where table column and row headings are concatenated into labels for the text input elements inside the table.

Note: The ARIA accessible name and description calculation specifies that the string specified in aria-labelledby should replace rather than add to the content of the element that carries the property. So adding the aria-labelledby property to a native label should replace the text content inside that label unless the label itself is referenced as part of the sequence of ids in aria-labelledby.

Examples

Example 1: A time-out input field with concatenated label

A text input allows users to extend the default time before a time-out occurs.

The string "Extend time-out to" is contained in a native label element and is associated with the input with the input by id="timeout-duration" . This label is associated with this input using the for/id association only on user agents that don't support ARIA. On user agents that support ARIA, the for/id association is ignored and the label for the input is provided only by aria-labelledby, per the accessible name and description calculation in the HTML to Platform Accessibility APIs Implementation Guide.

The aria-labelledby attribute on the text input references three elements: (1) the span containing the native label, (2) the text input containing the default text '20' (recall that this input is not labelled with the for/id associated label text), and (3) the string 'minutes' contained in a span. These elements should be concatenated to provide the full label for the text input

Note: The use of tabindex="-1" on the span element is not meant to support focusing by scripts - here, it merely serves to ensure that some browsers (IE9, IE10) will include the span element in the accessibility tree, thus making it available for reference by aria-labelledby. For more details see Accessible HTML Elements

Example 3: A conference workshop booking table

A conference workshop booking table with two parallel tracks allows users to select the workshop they want to attend. When tabbing through the checkbox inputs in the table, the track (1 or 2), the title, and the speaker of the workshop followed by the adjacent checkbox label "Attend" are provided as concatenated label for the checkboxes via aria-labelledby.

Related Techniques

Tests

Procedure

Check that ids referenced in aria-labelledby are unique and match the ids of the text nodes that together provide the label

Check that the concatenated content of elements referenced by aria-labelledby is descriptive for the purpose or function of the element labeled

Expected Results

#1 and #2 are true.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.