Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 39 ยท Forms and Accessibility

Focus and Keyboard Support in Web Components

Make custom elements keyboard friendly with tabindex, delegatesFocus, focus-visible styling and the roving tabindex pattern for toolbars, tabs and menus.

Many people never touch a mouse: keyboard users, screen reader users, people with motor impairments, and power users. A component that only responds to clicks locks them out. Keyboard support has three parts: a sensible tab order, visible focus, and the arrow-key and shortcut behavior that matches the role you promised in ARIA.

Shadow DOM adds a twist, because focus has to cross the boundary. This lesson covers how.

Making a host focusable

A custom element is not focusable by default. Add tabindex:

  • tabindex="0" puts the element in the normal tab order.
  • tabindex="-1" makes it focusable by script (el.focus()) but skips it when tabbing.
  • Avoid positive values; they override the natural order and are a maintenance trap.

Set it in connectedCallback only if the author did not provide one, so outside code can still decide:

JavaScript
connectedCallback() {
  if (!this.hasAttribute("tabindex")) this.tabIndex = 0;
}

Showing focus

Never remove the focus indicator without replacing it. Use :focus-visible, which shows the ring for keyboard focus but typically not for mouse clicks:

CSS
:host(:focus-visible) { outline: 3px solid #4a90e2; outline-offset: 2px; }

Inside a shadow root you can also react to focus on internals with :host(:focus-within).

delegatesFocus

If your shadow root contains a focusable control (say an <input>), you want the host to behave as if it were that input: clicking the host or calling host.focus() should focus the input, and clicking a <label> that points at the host should work. The option delegatesFocus: true on attachShadow does it.

delegatesFocus in action

Pressing the second button focuses the inner input and the border lights up. Calling focus() on the first does nothing visible, because the host itself is not focusable and does not delegate. Also note that document.activeElement reports the host, not the inner input; use host.shadowRoot.activeElement to see the real one.

delegatesFocus also changes focus on click: clicking non-focusable padding inside the shadow root moves focus to the first focusable item. It affects :focus styling too, so the host matches :focus when an inner element has focus.

Tab order across shadow boundaries

Tabbing follows the flattened tree in order, entering shadow roots naturally. You do not need extra work: a <button> in your shadow DOM is reached by Tab in its place in the document. Avoid tabindex values above zero and avoid trapping focus unless you are building a modal dialog.

The roving tabindex pattern

A toolbar with ten buttons should be one tab stop, not ten. Arrow keys move between items. The pattern:

  1. Exactly one item has tabindex="0"; the others have tabindex="-1".
  2. Arrow keys move the 0 to the next or previous item and focus it.
  3. Home and End jump to the first and last.
A roving tabindex toolbar

Tab from the first button: you land on one toolbar item, and the next Tab leaves the toolbar entirely. The focusin listener keeps the "current" item correct when someone clicks a button.

Keys to support, by pattern

Pattern Keys
Button-like Enter, Space
Switch / checkbox Space
Toolbar, tabs, radio group Arrows, Home, End
Menu / listbox Arrows, Home, End, type-ahead, Escape to close
Dialog Tab cycles inside, Escape closes, focus returns to opener

The WAI-ARIA Authoring Practices describe the expected keys for each role. Follow them rather than inventing new shortcuts.

Common mistakes

  • Using div plus click handlers with no tabindex or key handling.
  • Removing outlines (outline: none) without a replacement.
  • Forgetting preventDefault() on Space and arrow keys so the page scrolls while the component moves.
  • Moving focus with focus() before the element is visible or connected.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does tabindex="-1" do?

    -1 allows programmatic focus while keeping the element out of the Tab sequence.
  2. 2. What does delegatesFocus: true do?

    It forwards focus from the host to the first focusable internal element.
  3. 3. In a roving tabindex, how many items have tabindex="0" at once?

    One item is the single tab stop; the others are -1 and are reached with arrow keys.
  4. 4. Which pseudo-class shows a focus ring mainly for keyboard focus?

    :focus-visible matches when the browser decides the focus should be visibly indicated, usually after keyboard use.

Summary

  • Give custom hosts tabindex="0" (or none, if they wrap a focusable control).
  • Keep a clear :focus-visible indicator.
  • Use delegatesFocus: true when the host should hand focus to an inner control.
  • Use roving tabindex for composite widgets and follow the standard key maps.

Next: CSS Custom Properties for Theming