# ARIA toggle fields must have an accessible name.

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

ARIA toggle fields are interactive controls that let users select or switch between options. These include elements with roles such as `checkbox`, `switch`, `radio`, `menuitemcheckbox`, and `menuitemradio`. When any of these controls lacks an accessible name, assistive technology cannot convey what the control does. A screen reader might announce "checkbox, not checked" with no indication of what the checkbox is for, leaving the user to guess.

This affects screen reader users most directly, but it also creates problems for voice control users who need to reference controls by name to interact with them. Without an accessible name, there is no reliable way to target the control by speech.

## Why this matters

WCAG Success Criterion 4.1.2 (Name, Role, Value) at Level A requires that all user interface components have a name that can be programmatically determined. Toggle controls built with ARIA roles are no exception. Browsers and assistive technologies rely on the accessible name to communicate the purpose of each control. When that name is missing, the control is unusable for people who depend on assistive technology.

## How to fix it

There are several ways to give an ARIA toggle field an accessible name:

- Add visible text content inside the element. If the element contains text, that text becomes the accessible name.
- Use the `aria-label` attribute to provide a name directly on the element. This works when a visible label is not practical.
- Use `aria-labelledby` to point to another element that contains the label text. This is the best approach when a visible label already exists nearby.

Pick whichever method fits the design. A visible label is generally preferred because it benefits all users, not just those using assistive technology.

## Examples

### Missing accessible name

This checkbox has no text content, no `aria-label`, and no `aria-labelledby`. A screen reader will announce it as a checkbox with no label.

```html
<span role="checkbox" aria-checked="false" tabindex="0"></span>
```

This switch has the same problem:

```html
<div role="switch" aria-checked="false" tabindex="0"></div>
```

### Fixed with visible text content

Adding text inside the element gives it an accessible name automatically.

```html
<span role="checkbox" aria-checked="false" tabindex="0">
  Receive notifications
</span>
```

### Fixed with `aria-label`

When the control has no visible text (for example, it uses an icon or CSS to display its label), `aria-label` provides the name.

```html
<span role="switch" aria-checked="false" tabindex="0" aria-label="Dark mode"></span>
```

### Fixed with `aria-labelledby`

When a visible label exists as a separate element, use `aria-labelledby` to associate it with the control.

```html
<span id="label-notifications">Email notifications</span>
<span role="checkbox" aria-checked="false" tabindex="0" aria-labelledby="label-notifications"></span>
```

### Radio group with named radio buttons

Each `radio` in a group needs its own accessible name so users can distinguish between options.

```html
<div role="radiogroup" aria-label="Preferred contact method">
  <span role="radio" aria-checked="true" tabindex="0">Email</span>
  <span role="radio" aria-checked="false" tabindex="-1">Phone</span>
  <span role="radio" aria-checked="false" tabindex="-1">Text message</span>
</div>
```

### Menu item toggles with accessible names

Controls with roles `menuitemcheckbox` and `menuitemradio` also need names. Text content inside the element is the simplest approach.

```html
<ul role="menu">
  <li role="menuitemcheckbox" aria-checked="true">Show toolbar</li>
  <li role="menuitemcheckbox" aria-checked="false">Show sidebar</li>
</ul>
```