Button

A button differs from a link, which navigates to another page, view, or resource rather than performing an action on the current page.

Sighted users learn what a button does from its label, its visual presentation, and its context. Assistive technology users depend on button labels, semantics, properties, and states being conveyed to the assistive technology they use.

The following HTML elements are semantic buttons that natively convey their button role and other essential information to assistive technologies: <button>, <input type="button">, <input type="submit">, <input type="image">, and <input type="reset">.

Any of the native HTML semantic buttons automatically conveys its button role, name, and disabled state to assistive technology and is keyboard operable. Native HTML buttons go beyond what WCAG success criteria strictly require, so use them whenever possible.

A user can activate a native HTML button in many ways: by pointing and clicking with a mouse or other pointing device, by tapping a touch screen, by issuing a voice command through assistive technology that supports it, or by pressing the Enter or Space key. Each of these results in a click event that JavaScript can handle to perform the action.

Activating a button with any kind of pointing device can be canceled. The click event occurs when the user releases the mouse button, lifts the finger that tapped the touch screen, or completes whatever action their device requires to point and "click." To cancel, the user moves the pointer off the button before releasing it.

Current accessibility standards do not require a way to cancel button activation with a keyboard, but native HTML buttons provide one. The Enter key activates a button as soon as it's pressed. The Space key doesn't activate a button until it's released, and moving focus away from the button while holding the key down cancels the activation.

The Examples section discusses the ARIA attributes and JavaScript a generic HTML element needs to emulate a native HTML button.

This article covers the base accessibility requirements of buttons, however they're used. Some specialized button applications have additional accessibility requirements. Their entries are listed in Related Patterns.

When to Use

Use a button when:

• The control triggers an immediate action on the current page, such as submitting a form, saving, opening or closing a dialog, or confirming or canceling a choice.

Don't use a button when:

• The control takes the user to another page, view, or resource. Use a link so assistive technology users are aware that acting on it will cause a change of context.
• The control lets the user enter a value or select one from a set. Use a combobox, listbox, or another form of input.

Activating a button should never cause an unexpected change of context.

Examples

A native HTML button, such as the one in the following example, is accessible by default. The JavaScript that performs its action only needs to handle the click event for the button to be operable by all users. It's in the tab order and keyboard operable unless its disabled attribute is set.

<button id="save-button">Save changes</button>

document.getElementById('save-button').addEventListener(
    'click', () => { /* Save changes */ }
)

A custom button requires additional attributes and JavaScript to duplicate the built-in accessibility of the <button> element, as in the following simplified example.

To emulate a native HTML button, this custom button requires several code additions that come for free with <button>:

• The attribute role="button" is set to let assistive technology users know that the element is a button.
• The attribute tabindex="0" places the button in the tab order, allowing keyboard users to focus on it.
• The "Save changes" action is handled on the click event.
• Keyboard event handlers allow button activation by triggering a click event with the Enter keydown or Space keyup events.
• JavaScript can disable the button with saveButton.disabled = true and re-enable it with saveButton.disabled = false.
• Whenever the button is disabled, its action is prevented, the attribute aria-disabled="true" is set, and the button is removed from the tab order.

<div id="save-button" role="button" tabindex="0">Save changes</div>

class CustomButton {
    #element;


    constructor(element) {
        this.#element = element;
        this.#initialize();
    }


    #saveChanges() {
        /* code to save changes */
    }


    #initialize() {
        this.#element.setAttribute("role", "button");
        this.#element.tabIndex = 0;
        this.#element.addEventListener("click", (event) => {
            if (this.disabled) {
                event.preventDefault();
                event.stopImmediatePropagation();
                return;
            }
            this.#saveChanges();
        })
        this.#element.addEventListener("keydown", (event) => {
            if (this.disabled) return;
            if (event.key === "Enter") {
                event.preventDefault();
                this.#element.click();
            }
            else if (event.key === " ") {
                // prevent default page scroll
                event.preventDefault();
            }
        })
        this.#element.addEventListener("keyup", (event) => {
            if (this.disabled) return;
            if (event.key === " ") {
                event.preventDefault();
                this.#element.click();
            }
        })
    }


    get disabled() {
        return this.#element.getAttribute("aria-disabled") === "true";
    }


    set disabled(trueOrFalse) {
        const disable = Boolean(trueOrFalse);
        this.#element.setAttribute("aria-disabled", String(disable))
        this.#element.tabIndex = disable ? -1 : 0;
    }


}


const saveButton = new CustomButton(
    document.getElementById('save-button')
);

Structure and Semantics

A button is an interactive element that conveys its purpose to assistive technology through the button role and its accessible name, which together tell users what the button does and how to use it.

A button has no structure. The element <input type="button"> is defined by its attributes. A <button> element can have content, but assistive technologies use that content only to compute the button's accessible name. They treat the subtree of any element with the button role as presentational.

ARIA attributes can add semantic information to convey special-purpose properties or state to assistive technology:

Role

A button must expose the button role to assistive technology so that users know its purpose and how they can interact with it.

The HTML <button> and <input type="button"> elements expose the button role implicitly, requiring no additional ARIA. When you have to build a button from a different element, such as a non-semantic element or a semantic element that allows the button role, set role="button" on it explicitly.

Without the button role, screen readers announce a button as plain, non-interactive content or, with a different role, as the wrong kind of element. Users won't know its purpose or how to interact with it.

The following elements implicitly carry the button role:

• <button> and <input type="button"> can be used anywhere on a web page.
• <input type="image"> and <input type="submit"> can be used to submit a form.
• <input type="reset"> can be used to reset a form.

Button Name

By default, a button is named by its text content, and that name should say what the button does. Without a meaningful name, screen readers announce only "button," and users can't know what it does or tell it apart from other buttons.

Disabled

A button must convey its disabled state to assistive technologies.

Forbidden Interactive Children

Nested interactive elements create ambiguity for all users, who can't be certain which element will respond to their interaction.

Relationships

Buttons often control other elements to create user interfaces. When a button's presentation conveys a relationship to another element, the button should also convey it to assistive technology by setting aria-controls to the ID of the controlled element.

aria-owns

A button is a single control, not a container. Its children are presentational, so nothing inside a button reaches assistive technology except as part of its accessible name.

Operation

A button must be operable with both a pointer and a keyboard. Clicking or tapping the button activates it. On a keyboard, the Tab key moves focus to and away from a button, and pressing Enter or Space activates it.

Semantic HTML buttons provide this keyboard behavior automatically. A custom button built with role="button" must reproduce it: Add tabindex="0" so the element joins the tab order, and add event listeners to enable activation with the Enter or Space key. By convention, a button is activated on an Enter keydown event and a Space keyup event.

Focus Sequence

A button must be in the tab order and reachable with the Tab key when it's enabled, and should be removed from the tab order when it's disabled.

Keyboard Activation

Unless explicitly prevented, a click event can be triggered on any HTML element by someone using a mouse or other pointing device. Keyboard users can activate only native HTML interactive elements. Some elements, such as <a href="some-uri">, are activated with the Enter key, while others, such as <input type="checkbox">, are activated with the Space key. Unless it's disabled, a button activates with either the Enter or Space key.

For an interactive element, Enter and Space carry subtly different semantics: The Enter key most often triggers a do action, while the Space key generally triggers a select action, and a button honors both.

A button is activated on an Enter keydown event but on a Space keyup event so that a user can cancel the select action. To cancel it, the user tabs away from the button while holding the Space key down.

Event Listener Type

When script in a button responds to keys, it listens for keydown or keyup. The keypress event is deprecated, and browsers don't fire it for many keys, including the arrow keys, Home, End and Escape.

FAQ

Related Patterns

• Disclosure: a button that shows and hides a region of content
• Menu Button: a button that opens a menu
• Dialog: a dialog that a button usually opens
• Toggle Button: a button that switches between pressed and not pressed
• Link: navigates to another page, view, or resource instead of performing an action

Recommended Reading

• Button Pattern | W3C ARIA Authoring Practices Guide
• button role | W3C WAI-ARIA
• <button>: The Button element | MDN
• ARIA: button role | MDN
• ARIA in HTML | W3C