Checkboxes, radios and switches with no accessible name

What a toggle field name is

A toggle carries two pieces of information: what it controls, and whether it is on. ARIA covers the second with aria-checked. The first is the accessible name, and without it a screen reader says “checkbox, not checked” and stops.

Native checkboxes and radios take their name from a <label>. Custom toggles built from a <div> with role="switch" take theirs from aria-label, aria-labelledby or their own text content.

What squirrel checks

One check, aria-toggle-field-name, at severity error. It covers every element with role="checkbox", role="radio" or role="switch", plus native input[type="checkbox"] and input[type="radio"] that carry no explicit role.

A name is accepted from a non-empty aria-label, an aria-labelledby pointing at an element with text, a non-empty title, the element’s own text content, a <label for="..."> matching its id, or an ancestor <label> with text.

• Fail with N toggle field(s) without accessible names. Items read div[role="switch"], checkbox[name="terms"] or radio[name="plan"][value="pro"], up to ten with a count of the rest.
• Pass with All toggle fields have accessible names.
• aria-toggle-field-name-unconfirmed warns with N toggle field(s) without accessible names may be hidden by a style (unconfirmed) for a toggle field a style may hide in a way squirrel cannot settle.

Hidden toggle fields

A toggle field out of the accessibility tree has nothing to announce, so it is not reported: one with the hidden attribute (except hidden="until-found"), aria-hidden="true" on itself or an ancestor, display: none on itself or an ancestor (set inline or by a <style> rule squirrel can decide), or inside a closed <dialog> or an unopened popover. It still needs a name before it is shown. When every unnamed one is skipped this way, the pass reads All toggle fields in the accessibility tree have accessible names, with hiddenWithoutName in its details.

squirrel reads the markup, inline styles and the page’s <style> blocks, the same way as form-labels; see form-labels for what it can and cannot decide. External stylesheets are not read. A toggle field that carries a no-js class, itself or on an ancestor other than <html>, is reported as unconfirmed on a page with an external stylesheet or an @import, because a theme usually hides that fallback with a rule such as .js .no-js { display: none } once JavaScript runs.

How to fix it

<label>
  <input type="checkbox" name="terms">
  I accept the terms
</label>

Wrapping is the shortest fix for a native control, and it makes the words clickable as well.

For a custom toggle, put the name on the element with the role and keep aria-checked in step with the visible state:

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

A group of radios needs one name per radio, not one for the group. The group label belongs on a <fieldset> with a <legend>, or on a role="radiogroup" container.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/aria-toggle-field-name"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/aria-toggle-field-name"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/aria-required-attr: aria-checked, which those same roles must declare.
• a11y/aria-input-field-name: the wider naming sweep across input roles.
• a11y/form-labels: the same label association checked across inputs, textareas and selects.
• a11y/form-field-multiple-labels: two labels pointing at one control.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• The checkbox role, MDN
• The switch role, MDN
• Labeling controls, W3C WAI tutorials

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Native and custom toggles are listed together, each with a selector. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.