Custom controls must have appropriate ARIA roles.
Description
This rule checks that focusable non-native elements – such as <div>, <span>, <p>, <section>, <ul>, <li>, <img> and <label> carrying a tabindex other than -1 – expose an appropriate ARIA widget role. When an author makes a generic element keyboard-focusable but does not declare its semantics with a role attribute, assistive technologies can no longer tell that the element is a control, what it does, or how to operate it. Focusable non-native controls must expose their role programmatically.
The check is part of WCAG Success Criterion 4.1.2 Name, Role, Value (Level A), which requires that every user interface component has a programmatically determinable role. The validator reports an issue only when the focusable element has no valid widget role from the ARIA widget taxonomy (such as role="button" or role="switch"), and it skips native interactive elements like <button>, <a href>, <input>, <select>, <textarea>, <details> and <summary> because their roles are implicit.
Disabilities impacted
- Visual impairments (screen reader users) – People who rely on screen readers receive a reconstructed, audio version of the page built from the accessibility tree. A focusable
<div>or<span>without a role is announced as generic content – often as “group” or “text” – so the user cannot tell that it is a button or a switch and has no idea how to interact with it. - Low vision – Users who magnify the screen or use voice-driven interfaces depend on programmatic semantics because small visual affordances (shadows, borders, hover styling) are hard to see. A missing role means assistive tools cannot offer sensible commands such as “activate” or “toggle”.
- Motor disabilities – Users who operate devices through switches, eye tracking or voice control cannot click a mouse. They rely on keyboard focus plus announced semantics to navigate. Without a role, a custom control receives focus without signaling that it is actionable, so these users skip it entirely or trigger unexpected behavior.
- Cognitive disabilities – Predictable, self-describing controls reduce confusion. When a control looks like a toggle but is announced as plain text, users may misinterpret its behavior, lose confidence in the interface, or abandon the task.
Why it matters
WCAG 4.1.2 exists because assistive technologies cannot infer meaning from appearance alone. The role attribute is the contract between a custom widget and the accessibility tree: it tells the screen reader what the control is (its identity), which states it supports, and how to activate it. Without that contract, robust accessibility breaks even when the page works perfectly with a mouse, and the content fails WCAG conformance at Level A.
Adding the correct role is also the foundation for other requirements. A role such as role="switch" implies that an aria-checked state must follow, that the element must be reachable with the keyboard per 2.1.1, and that focus must be visible per 2.4.7. The single attribute therefore cascades into correct announcement, state reporting and operation for motor, visual and cognitive – controls that speak their own semantics work for everyone.
Coding problems and solutions
Common coding problems
- Focusable without a role – Adding
tabindex="0"to a<div>,<span>or<img>to make it clickable, but omitting theroleattribute. The element is in the tab order yet has no programmatic identity, which triggers this rule. - A non-widget role value – Assigning a role that is not a widget role, such as
role="presentation",role="heading"or an invalid custom string, on a focusable element. Assistive technologies do not treat those as operable controls, so the element still fails. - Redundant roles on native controls – Writing
<button role="button">or<a href="#" role="link">. Native elements already expose their role; repeating it adds noise, and overriding it can delete required semantics. - Relying on visual cues or
titleonly – Using shape, color, border or a hover-onlytitletooltip to signal that something is a control. Non-visual users never see these cues, and nothing is added to the accessibility tree. - Click-only keyboard handling – Making a
divrespond to aclickevent without handling Enter and Space. Even with a correct role, the control fails keyboard operability and is announced but impossible to activate from the keyboard.
How to fix it
Prefer native semantic elements
The simplest fix is to avoid custom controls altogether. Native elements such as <button> and <a href> ship with the correct role, keyboard handling, focus management and form behavior built in, so no extra ARIA is needed and this rule cannot fire.
<button type="button">Save changes</button><div tabindex="0" class="button">Save changes</div>Add an appropriate ARIA role
When a non-native element must become a control, give it a widget role that matches its behavior: button, switch, checkbox, slider, tab, link, and so on. The role must be one of the valid ARIA widget roles for the validator to pass, and the element must expose the states its role implies (for example, aria-checked on a switch).
<span tabindex="0" role="switch" aria-checked="false">Enable notifications</span><span tabindex="0" aria-checked="false">Enable notifications</span>Make the control keyboard operable
A correct role is useless if the control cannot be activated with the keyboard. Handle activation for the keys users expect: Enter and Space for buttons and switches, arrow keys for sliders and radio groups. Prefer addEventListener with a named handler over inline event handler attributes.
<div tabindex="0" role="button" id="customBtn">Confirm</div>
<script>
const customBtn = document.getElementById('customBtn');
const activateButton = () => {
submitForm();
};
const handleButtonKeydown = (event) => {
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
activateButton();
}
};
customBtn.addEventListener('click', activateButton);
customBtn.addEventListener('keydown', handleButtonKeydown);
</script><div tabindex="0" role="button" id="customBtn" onclick="submitForm()">Confirm</div>
<script>
const customBtn = document.getElementById('customBtn');
customBtn.addEventListener('click', submitForm);
</script>Provide an accessible name and announce state changes
Alongside the role, every control needs an accessible name. Add a visible text label when possible; otherwise use aria-label or aria-labelledby. When a custom control changes state, make the change obvious to assistive technologies – for example, with an aria-live region – and keep timer-based announcements tidy with globalThis.setTimeout(), a function reference, a full-number delay and cleanup in a beforeunload handler.
<div role="switch" tabindex="0" aria-checked="false" aria-label="Enable notifications">Enable notifications</div>
<script>
const hideToast = () => {
toastEl.classList.add('hidden');
};
const toastTimerId = globalThis.setTimeout(hideToast, 30000);
window.addEventListener('beforeunload', () => {
globalThis.clearTimeout(toastTimerId);
});
</script><div role="switch" tabindex="0" aria-checked="false" title="Enable notifications">Enable notifications</div>
<script>
globalThis.setTimeout("hideToast()", 30000);
</script>Known Limitations
- Attribute presence only – The check verifies that a valid widget role exists; it cannot prove that the control is actually operable, that focus is managed correctly, or that
click, Enter and Space all work. Those behaviors still require manual testing. - Single-page applications – The audit runs once against the rendered DOM. Controls injected after the audit (modal toggles, lazy-loaded drawers, virtualized lists) are not rechecked automatically, so a fresh audit is needed after those elements appear.
- Shadow DOM – Page-level selectors do not pierce shadow roots by default. A custom control rendered inside a Web Component shadow tree will not be inspected, even if it is focusable and lacks a role.
- iframes – Interactive markup inside iframed or cross-origin documents is not part of the audited document tree and will not be validated by this rule.
- Hidden and programmatically focusable elements – Elements that are not visible (for example,
display: none) or that usetabindex="-1"for scripted focus management are skipped. Such controls must be reviewed manually when they become visible or receive focus. - No behavior inference – The rule cannot tell what the widget actually does. An element with
role="button"that performs no action passes automatically, so human judgment remains necessary to confirm meaningful behavior.
Resources
- WCAG 2.2 Understanding Success Criterion 4.1.2 – Name, Role, Value
- W3C ARIA 1.2 – Roles definition
- WAI-ARIA Authoring Practices Guide (APG)
- MDN – ARIA overview
- MDN – The tabindex attribute
Rule
- Audit: accessibility
- Standard: WCAG
- Level: A
- Success Criteria: 4.1.2
- Rule ID:
custom-control-role