# ARIA commands must have an accessible name.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/labels-and-names/aria-command-name
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

Elements with ARIA command roles (`button`, `link`, `menuitem`) must have an accessible name. Without one, assistive technologies cannot convey what the element does, leaving users unable to determine its purpose or distinguish it from other interactive controls on the page.

Screen reader users are the most directly affected. When a screen reader encounters a `button` or `menuitem` that has no accessible name, it may announce only the role (e.g., "button") with no indication of the action it performs. A sighted user might infer purpose from an icon, but a screen reader user hears nothing useful. This makes the interface effectively unusable for that control.

This rule maps to WCAG 2 success criterion **4.1.2 Name, Role, Value** (Level A). That criterion requires all user interface components to have a name that can be programmatically determined. Level A means this is a baseline requirement — failing it is a conformance blocker.

## Why this happens

The most common cause is an interactive element that contains only an image (or icon font) with no text alternative. For example, a `button` with `role="menuitem"` that contains only an `<img>` with an empty `alt` attribute produces no accessible name. The same problem occurs when an element has no text content and no `aria-label`, `aria-labelledby`, or `title` attribute.

Off-screen elements are not exempt. Even if a command is positioned off screen with CSS, it may still be present in the accessibility tree. If it lacks a name, it still fails this rule.

## How to fix it

There are several ways to give an ARIA command an accessible name:

1. Add visible text content inside the element. This is the simplest and most reliable approach.
2. Add an `aria-label` attribute with a descriptive string.
3. Use `aria-labelledby` to reference another element that contains the label text.
4. As a last resort, use the `title` attribute. Note that `title` has inconsistent support across assistive technologies and is generally less reliable than the other options.

Choose whichever method fits the design. Visible text content is preferred because it benefits all users, not just those using assistive technology.

## Examples

### Failing: menuitem with icon but no accessible name

The image has an empty `alt` attribute, and the button has no `aria-label` or text content. A screen reader will announce something like "menuitem" with no indication of what it does.

```html
<div role="menu">
  <button role="menuitem">
    <img src="file-icon.svg" alt="" />
  </button>
</div>
```

### Failing: off-screen menuitem with no accessible name

Moving the menu off screen does not remove it from the accessibility tree. The button still lacks a name.

```html
<style>
  .offscreen {
    position: absolute;
    left: -9999px;
  }
</style>
<div role="menu" class="offscreen">
  <button role="menuitem">
    <img src="file-icon.svg" alt="" />
  </button>
</div>
```

### Passing: menuitem with visible text content

```html
<div role="menu">
  <button role="menuitem">New file</button>
</div>
```

### Passing: menuitem with `aria-label`

When visible text is not possible (for example, an icon-only button), `aria-label` provides the name directly.

```html
<div role="menu">
  <button role="menuitem" aria-label="New file">
    <img src="file-icon.svg" alt="" />
  </button>
</div>
```

### Passing: menuitem with `aria-labelledby`

The `aria-labelledby` attribute points to an element that contains the label text. The referenced element can be visually hidden.

```html
<div role="menu">
  <button role="menuitem" aria-labelledby="newfile-label">
    <img src="file-icon.svg" alt="" />
  </button>
  <span id="newfile-label" hidden>New file</span>
</div>
```

### Passing: link role with visible text

The same rules apply to other ARIA command roles. A `link` role needs a name just like a `menuitem` does.

```html
<span role="link" tabindex="0">View documentation</span>
```

### Failing: link role with no accessible name

```html
<span role="link" tabindex="0">
  <img src="external-link.svg" alt="" />
</span>
```

To fix this, add `aria-label="View documentation"` to the `span`, or give the `img` a descriptive `alt` value.