# Including the text of the visible label as part of the accessible name

## Metadata

general

sufficient

## When to Use

This Technique applies to all web technologies that include interactive controls (such as links or form inputs)

## Description

The objective of this technique is to ensure that speech input users can operate web content reliably.

When speech input users interact with a web page, they usually speak a command followed by the reference to some visible label (like text in a button, the link text, or the text labelling input fields). For example, they may speak "click search" to activate a search button.

When speech recognition software processes speech input and looks for matches, it uses the "accessible name" of controls, which can be different from the visible label. For example, a button following a search input field may contain the text "go" but uses an invisible `aria-label` attribute with the value "search". Since aria-label takes precedence over the text included in the button, the accessible name of this button will be "search", not "go". The Accessible Name and Description Computation defines how the accessible name is constructed.

In situations where the visible label is considered inadequate as the accessible name, it is possible to supplement text in the accessible name. However, in order to meet 2.5.3 Label in Name, the text string that makes up the visible label must occur in its entirety in the accessible name. In most situations, where it is felt that additional context is needed, it is recommended that the visible text should precede the additional text. When authors make sure that the visible label of a control is included, intact, in the accessible name of that control, speech input users can be confident that their input will be correctly interpreted.

Additional context may be more appropriately included using the Accessible Description (including through use of `aria-describedby`). This has the signficant benefit of improving context for some users of assistive technology without altering the accessible name.

## Examples

### Link text matches the beginning of the accessible name

A link contains visible text and hidden link text. Both together make up the link's accessible name. The visible text comes first. The idea is to make the link more descriptive for users of assistive technologies.

`<p>Go to <a href="code-of-conduct.html">Code of conduct <span class="hidden_accessibly"> of ACME Corporation</span></a><p>`

### Generic link text concatenated with heading

A generic link is combined with the heading of the paragraph to give context. It is a variation on the first example, this time using `aria-labelledby`. The advantage of this implementation is that it uses existing visible text on the page, and so is more likely to be properly translated during any localization transformations.

`<h4 id="poor">Insufficient Link Names Invade Community</h4>
<p>Citizens are reeling from the growing invasion of useless "read more" links appearing in their online resources. <a href="poor.html" aria-labelledby="generic poor"><span id="generic">More...</span></a>`

#### Insufficient Link Names Invade Community

[The following link opens nothing] Citizens are reeling from the growing invasion of useless "read more" links appearing in their online resources. More...

### Link text included in `aria-label`

Where two strings cannot be grammatically or seamlessly combined using `aria-labelledby`, `aria-label` can be used to make a new name which includes the visible label.

`...end of news story. <a href="poor.html" aria-label="Read more about Insufficient link names">Read more</a>`

### The visible button text matches the beginning of the accessible name

The visible text inside a `button` element matches the beginning of accessible name, which also includes hidden text. The idea of the hidden text is to make the button more descriptive for users of assistive technologies.

`<button>Send <span class="accessibly-hidden"> Mail</span></button>`

## Resources

- Accessible Name and Description Computation 1.1
- HTML 5 Accessible Name and Description Computation

## Tests

### Procedure

For all controls with a visible label, check that:

1. The accessible name of the control contains the same letters in the same order as the visible label.

### Expected Results

- Check #1 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.

## Related Techniques

- ARIA7: Using `aria-labelledby` for link purpose
- ARIA8: Using `aria-label` for link purpose
- ARIA9: Using `aria-labelledby` to concatenate a label from several text nodes
- ARIA16: Using `aria-labelledby` to provide a name for user interface controls
- SCR30: Using scripts to change the link text