« 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. This page also covers <input> elements of type submit, reset, and image, which share button semantics but not always the same naming mechanism.

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">

<input type="submit">

Recommended. Like <input type="button">, the value attribute provides both the visible label and the accessible name. Without a value, the browser supplies its own default label, and that default isn't guaranteed to be the same string across browsers or locales.

The accessible name for the first button should be: Create account. The second has no value attribute, so its accessible name comes from the browser's own default label, confirm directly what that actually is in your standard browsers rather than assuming.

<input type="submit" value="Create account">
<input type="submit"> <!-- no value: browser-supplied default label -->

<input type="reset">

Recommended. Same mechanism as submit and button, the value attribute provides both the visible label and the accessible name, with the same browser-default caveat when it's omitted.

The accessible name for the first button should be: Clear form. The second has no value attribute, confirm directly what default label your standard browsers supply.

<input type="reset" value="Clear form">
<input type="reset"> <!-- no value: browser-supplied default label -->

<input type="image">

Recommended when used, though a native <button> containing an <img> is usually more flexible. Unlike the other input button types, <input type="image"> takes its accessible name from the alt attribute, the same mechanism as a plain <img>, not from value.

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

<input type="image" src="search-icon.png" alt="Search">

<input type="image">, no accessible name

Never do this. The same failure as a bare <button></button>, but here the missing piece is alt, since this element has no visible text of its own to fall back on at all.

There is no accessible name for this <button>.

<input type="image" src="search-icon.png"> <!-- no alt -->

<input type="image">, name via title

Avoid. If alt is missing, some browsers fall back to title to supply an accessible name, the same reliability problem as relying on title for a native <button>, not guaranteed, and not discoverable to sighted users.

The accessible name for this <button> should be: Search, worth confirming directly, this fallback isn't guaranteed across browsers.

<input type="image" src="search-icon.png" title="Search"> <!-- no alt -->

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