« Back to home

Testing buttons

While all of these examples demonstrate how an accessible name can be calculated, they are not all examples of good practice. Some techniques override visible text, rely on attributes that are poorly supported or undiscoverable, or recreate native functionality unnecessarily. Whenever possible, use native HTML buttons with visible text, and only use ARIA when there is no suitable native solution.

Name from content

Recommended. The visible button text becomes the accessible name, making it simple, reliable and consistent for everyone.

The accessible name for this <button> should be: Hello world

<button>Hello world</button>

Name via aria-labelledby

Use with care. This overrides the button's own text and should only be used when another visible label needs to provide the accessible name.

This example fails WCAG 2.5.3 Label in Name because the visible text ("Close") does not match the accessible name ("Dismiss").

The accessible name for this <button> should be: Dismiss

<button aria-labelledby="aaa">Close</button>
<p id="aaa">Dismiss</p>

Name via aria-label

Avoid when visible text exists. This replaces the visible text as the accessible name, which can create inconsistencies for screen reader and voice control users. Use it only when the visible text needs additional context that is not appropriate to display on screen.

This example fails WCAG 2.5.3 Label in Name because the visible text ("Add to cart") does not match the accessible name ("Save this item").

The accessible name for this <button> should be: Save this item

<button aria-label="Save this item">Add to cart</button>

Name via title

Avoid. The title attribute is not reliably exposed or discoverable and should not be relied upon to provide the accessible name for a button.

The accessible name for this <button> should be: Continue

<button title="Continue"></button>

Name via value

Recommended for <input type="button">. The value attribute provides both the visible label and the accessible name.

The accessible name for this <button> should be: Create account

<input type="button" value="Create account">

Name via role="button"

Avoid where possible. Use a native <button> instead, as custom buttons require additional keyboard interaction, focus management and state handling.

The accessible name for this <button> should be: Submit

<div role="button" tabindex="0">Submit</div>

No accessible name

Never do this. Buttons without an accessible name cannot be identified by assistive technologies, making them unusable for many people.

There is no accessible name for this <button>.

<button></button>

« Back to home