Using the button role

The button role should be used for clickable elements that trigger a response when activated by the user. On its own, role="button" can make any element (e.g. <p>, <span> or <div>) appears as a button control to a screen reader. Additionally, this role can be used in combination with the aria-pressed attribute in order to create toggle buttons. 

Note: Where possible, it is recommended to use native HTML buttons (<button>, <input type="button" /> and <input type="image" />) rather than the button role, as native HTML buttons are more widely supported by older user agents and assistive technology. Native HTML buttons also support keyboard and focus requirements by default, without need for additional customization. 

Keyboard and focus

Buttons are interactive controls, and therefore must be focusable. If the button role is added to an element that is not focusable by itself (such as <span><div> or <p>) the tabindex attribute will have to be used to make the button focusable.

Buttons need to be operable by mouse users as well as keyboard users. For native HTML buttons, the button's onclick event will fire both for mouse clicks and when the space key is pressed while the button has focus. If role="button" is used to create a custom button, the onclick event will only fire when clicked by the mouse cursor. Because of this, the developer will have to explicitly add a separate key event handler to the element so that the button can be triggered when the space key is pressed.

Warning: Be careful when marking up links with the button role. Buttons are expected to be triggered using the Space key, while links are expected to be triggered through the Enter key. In other words, when links are used to behave like buttons, adding role="button" alone is not sufficient. It will also be necessary to add a key event handler that listens for the Space key in order to be consistent with native buttons.

Toggle buttons

An advantage of using role="button" is that it allows the creation of toggle buttons. A toggle button can have two states: pressed and not pressed. Whether or not a button is a toggle button can be indicated with the aria-pressed attribute in addition to the button role:

  • If aria-pressed is not used the button is not a toggle buttton.
  • If aria-pressed="false" is used the button is a toggle button that is currently not pressed. 
  • If aria-pressed="true" is used the button is a toggle button that is currently pressed.
  • if aria-pressed="mixed" is used, the button is considered to be partially pressed.

Labeling buttons

Buttons always need to have an accessible name. For most buttons, this name will be the same as the text inside the button. In some cases, for example for icon buttons, the accessible name can be provided through an aria-label or aria-labelledby attribute.

Possible effects on user agents and assistive technology 

When the button role is used, user agents should expose the element as a button control in the operating system's accessibility API. Screen readers should announce the element as a button and describe its accessible name. Speech recognition software should allow the button to be activated by saying "click" followed by the button's accessible name.=

Note: Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: A basic button

In the snippet below a span element is given the button role. Because a <span> element is used, the tabindex attribute is required to make the button focusable and part of the tab order. Note that this snippet implies that CSS styles are provided to make the <span> element look like a button and that handleBtnClick and handleBtnKeyUp are event handlers that perform the button's action when clicked and when the Space key is pressed. 

<span role="button" tabindex="0" onclick="handleBtnClick()" onKeyUp="handleBtnKeyUp()">Save</span>

Example 2: A toggle button

In this snippet a native HTML button is converted to a toggle button using the aria-pressed attribute. Note that the tabindex attribute does not have to be used here because the <button> element is already focusable by default. When the button is activated, the aria-pressed value switches between true and false;

<!DOCTYPE HTML>
<html lang="en-US">
<head>
 <meta charset="UTF-8">
 <title>ARIA Button Role Example</title>
 <style type="text/css">
  [role="button"] {
   padding:3px;
   border: 1px solid #CCC;
  }
  [role="button"][aria-pressed="true"] {
   border: 2px solid #000;
  }
 </style>
 <script type="text/javascript">
  function handleBtnClick(event) {
    event = event || window.event;
    var pressed = event.target.getAttribute("aria-pressed") == "true";
    //change the aria-pressed value as the button is toggled:
    event.target.setAttribute("aria-pressed", pressed ? "false" : "true");
    //... (perform the button's logic here)
  }

  function handleBtnKeyUp(event) {
    event = event || window.event;
    if (event.keyCode === 32) { // check for Space key
      handleBtnClick(event);
    }
  }
 </script>
</head>
<body>
 <button role="button" aria-pressed="false" onclick="handleBtnClick(event)" onKeyUp="handleBtnKeyUp(event)">Edit Mode</button>
</body>
</html>

Working Examples:

Notes 

ARIA attributes used

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

Document Tags and Contributors

Last updated by: smarvin,