element-not-activated-by-keyboard

Keyboard users move to a control with the Tab key, and activate it with Enter or Space. Native controls, such as <button>, handle these keys for you. A custom control built from a generic element, such as a <div> or a <span>, doesn't: it reacts only to the events your script listens for.

When a custom control can receive focus but listens only for mouse clicks, keyboard users can reach it, but pressing Enter or Space does nothing. They can see the control and focus it, but they can't use it.

Evinced reports this issue when an element can be activated with a mouse click, but not with the Enter or Space key.

To fix the issue:

• If possible, replace the custom element with the equivalent native HTML element. Native elements provide built-in keyboard support, and usually need only a click event handler.
• If a native element can't be used, add keyboard event listeners that trigger the same action as a mouse click when the Enter or Space key is pressed.

Pass Patterns

Native button

A native <button> activates with Enter and Space, so a click handler is all it needs.

<button type="button" onclick="addToCart()">Add to cart</button>

Custom button with keyboard handlers

The custom button activates on Enter when the key goes down, and on Space when the key comes up, the same as a native button. Pressing Space doesn't scroll the page, because its default action is cancelled.

<div role="button" tabindex="0" id="add-to-cart">Add to cart</div>


<script>
    const button = document.getElementById("add-to-cart");


    button.addEventListener("click", addToCart);


    button.addEventListener("keydown", (event) => {
        if (event.key === "Enter") {
            event.preventDefault();
            addToCart();
        }
        if (event.key === " ") {
            event.preventDefault();
        }
    });


    button.addEventListener("keyup", (event) => {
        if (event.key === " ") {
            addToCart();
        }
    });
</script>

Fail Patterns

Focusable custom button with only a click handler

The <div> has a role and tabindex="0", so keyboard users can reach it, but it listens only for clicks, so Enter and Space do nothing.

<div role="button" tabindex="0" onclick="addToCart()">Add to cart</div>

Focusable icon with only a click handler

The star can receive focus, but nothing happens when keyboard users press Enter or Space on it.

<span class="favorite-icon" tabindex="0" onclick="toggleFavorite()" aria-label="Add to favorites">☆</span>

WCAG techniques

Sufficient techniques

• G90: Providing keyboard-triggered event handlers
• G202: Ensuring keyboard control for all functionality
• H91: Using HTML form controls and links
• SCR20: Using both keyboard and other device-specific functions

Failure techniques

• F54: Failure of Success Criterion 2.1.1 due to using only pointing-device-specific event handlers (including gesture) for a function

Try It Yourself

Using a keyboard

1. Open the page in a browser, without using a screen reader.
2. Press the Tab key until the control has focus.
3. Press Enter. If nothing happens, press Space.

Expected results: The control performs the same action as when it's clicked with a mouse.

Actual results: The control receives focus, but nothing happens when Enter or Space is pressed.

Inspecting the browser dev-tools

1. In your browser's dev tools, select the control and open its event listeners panel.
2. Check which events the control, or one of its ancestors, listens for.

Expected results: The control is a native element, or it has a keydown or keyup listener that handles Enter and Space.

Actual results: The control has a click listener, but no listener for keyboard events.

FAQ

Standards and Regulations

Personas impacted by this issue

• Keyboard
• Motor and Mobility
• Switch Access

Learn More

• Understanding Success Criterion 2.1.1: Keyboard
• WAI-ARIA Authoring Practices: Button Pattern
• HTML Semantics and Accessibility
• Button UI pattern

Related Issues

• keyboard-accessible
• interactable-role
• anchor-without-href