HtmlHow-ToBeginner · 4 min read

How to Make Custom Element Keyboard Accessible in HTML

To make a custom element keyboard accessible in HTML, add a tabindex="0" attribute to make it focusable, assign appropriate role attributes for screen readers, and handle keyboard events like keydown to support keyboard interaction. This ensures users can navigate and use the element with a keyboard.

📐

Syntax

Use the following key parts to make a custom element keyboard accessible:

tabindex="0": Makes the element focusable by keyboard (Tab key).
role="button" (or other ARIA roles): Defines the element's purpose for screen readers.
Keyboard event listeners (e.g., keydown): Handle keys like Enter and Space to activate the element.

html

<div tabindex="0" role="button" aria-pressed="false">Custom Button</div>

Output

A focusable custom button element that screen readers recognize as a button.

💻

Example

This example shows a custom div acting like a button. It is focusable with Tab, announces as a button to screen readers, and responds to Enter and Space keys.

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Keyboard Accessible Custom Element</title>
  <style>
    .custom-button {
      display: inline-block;
      padding: 0.5rem 1rem;
      background-color: #007BFF;
      color: white;
      border-radius: 0.25rem;
      cursor: pointer;
      user-select: none;
      outline: none;
    }
    .custom-button:focus {
      outline: 3px solid #FFD700;
    }
  </style>
</head>
<body>
  <div tabindex="0" role="button" aria-pressed="false" class="custom-button" id="customBtn">
    Press Me
  </div>

  <script>
    const btn = document.getElementById('customBtn');

    btn.addEventListener('click', () => {
      alert('Button clicked!');
    });

    btn.addEventListener('keydown', (event) => {
      if (event.key === 'Enter' || event.key === ' ') {
        event.preventDefault();
        btn.click();
      }
    });
  </script>
</body>
</html>

Output

A blue rectangular custom button labeled 'Press Me' that can be focused with Tab and activated by clicking or pressing Enter/Space, showing an alert.

⚠️

Common Pitfalls

Common mistakes when making custom elements keyboard accessible include:

Not adding tabindex="0", so the element cannot be focused by keyboard.
Missing ARIA roles, causing screen readers to not recognize the element's purpose.
Not handling keyboard events like Enter or Space, so keyboard users cannot activate the element.
Using tabindex="-1" which removes the element from keyboard navigation.

html

<!-- Wrong: Not focusable and no keyboard support -->
<div role="button">Click me</div>

<!-- Right: Focusable and keyboard handled -->
<div tabindex="0" role="button" id="btn">Click me</div>
<script>
  const btn = document.getElementById('btn');
  btn.addEventListener('keydown', e => {
    if(e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      btn.click();
    }
  });
</script>

Output

The first div is not focusable or keyboard operable; the second div is focusable and activates on Enter/Space keys.

📊

Quick Reference

Attribute/Action	Purpose	Example
tabindex="0"	Makes element focusable by keyboard
role="button"	Announces element as button to screen readers
Keyboard event handling	Supports Enter/Space key activation	element.addEventListener('keydown', handler)
aria-pressed	Indicates toggle state for buttons	aria-pressed="true" or "false"
Focus style	Visible outline for keyboard focus	CSS :focus { outline: 3px solid; }

✅

Key Takeaways

Add tabindex="0" to make custom elements focusable by keyboard.

Use appropriate ARIA roles like role="button" to inform assistive technologies.

Handle keyboard events such as Enter and Space to activate the element.

Provide visible focus styles so keyboard users know which element is focused.

Avoid tabindex="-1" unless you want to remove the element from keyboard navigation.