References

Beginner-friendly references for web development, with live, editable examples.

The HTML aria-pressed attribute

ARIA Accessibility All modern browsers Updated
In short

The aria-pressed attribute marks a <button> as a toggle and states whether it is on. Use aria-pressed="true" or "false", or "mixed" for a partly applied state, and update it with JavaScript on every click.

Overview

The aria-pressed attribute turns a button into a toggle button and tells assistive technology whether it is currently pressed. Its values are true, false and mixed. Leaving it off, or setting undefined, means the button is an ordinary command button, not a toggle.

WAI-ARIA allows it on the button role, which includes a native <button>. HTML's button element has no pressed state of its own, so this is one of the cases where ARIA adds something HTML lacks. In our Chrome test, the accessibility tree reported pressed as true, false or mixed for the matching values.

The mixed value is for a button that controls several items whose states differ, such as a Bold button when only part of the selected text is bold. You have to change the value in JavaScript on every click, because the browser never updates it for you.

Keep the label the same in both states. The WAI-ARIA Authoring Practices say the label of a toggle must not change when its state changes, so a Mute button stays Mute and aria-pressed carries the on or off. A button whose text flips between Mute and Unmute should not use aria-pressed at all.

Syntax

<button type="button" aria-pressed="false">Mute</button>

Values

Value
true | false | mixed | undefined

Example

Live example 
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>aria-pressed toggle</title>
<style>
  #mute[aria-pressed="true"] { background: #1e72e0; color: #fff; }
</style>
</head>
<body>
<button type="button" id="mute" aria-pressed="false">Mute</button>
<script>
document.getElementById('mute').addEventListener('click', function () {
  const on = this.getAttribute('aria-pressed') === 'true';
  this.setAttribute('aria-pressed', String(!on));
});
</script>
</body>
</html>

Best practices

  • Put aria-pressed on a real <button>, which already handles focus, clicks and the Enter and Space keys.
  • Set aria-pressed to true or false from the start, and update it in the same click handler that changes the state.
  • Keep the visible label constant and style the pressed look from the attribute, for example with a [aria-pressed="true"] selector.
  • Don't combine aria-pressed with aria-checked or with a label that flips between two actions.

Frequently asked questions

What does aria-pressed do?
aria-pressed marks a button as a toggle and reports whether it is pressed. Assistive technology can then announce the button as pressed or not pressed.
What is the difference between aria-pressed and aria-checked?
Use aria-pressed on toggle buttons and aria-checked on checkboxes, radios and switches. WAI-ARIA notes that operating systems support pressed on buttons and checked on checkboxes.
What is the difference between aria-pressed and aria-selected?
aria-selected marks the chosen item in a set, such as a tab, an option or a grid cell. aria-pressed marks a standalone button that switches something on or off.
When should I use aria-pressed=mixed?
Use aria-pressed=mixed when the button controls several items that don't all share the same state. A Bold button over text that is only partly bold is a typical case.
Should the button text change when aria-pressed changes?
No, keep the label fixed and let aria-pressed carry the state. The WAI-ARIA Authoring Practices say a toggle's label must not change when its state changes.
Can I use aria-pressed on a checkbox?
aria-pressed belongs to the button role, not the checkbox role. ARIA in HTML allows it on input type=checkbox only when that input is given role=button, and a native checkbox already reports checked.
aria-posinset aria-readonly