Shadow DOM Focus Delegation: Getting delegatesFocus Right

Managing focus in the shadow DOM can be tricky. Developers often wrap a native with a component, adding a manual focus() override. Although it works, there is a simpler solution according to the spec: delegatesFocus.

delegatesFocus simplifies focus management:

What delegatesFocus Does

With delegatesFocus: true, the browser automatically handles responsibilities that would otherwise require manual focus management.

1) Clicks on the Host Element

Clicks on the host element redirect focus to the first focusable element in the shadow root, eliminating the need for this.shadowRoot.querySelector('button').focus().

2) Selector Matching

The host element matches :focus and :focus-within CSS pseudo-classes when an internal element is focused, enabling CSS styling for the host’s focus ring without JavaScript.

3) No Stranded Focus

delegatesFocus removes dead focus zones, ensuring interactions with the host move focus to the internal control, maintaining accessibility.

These behaviors simplify common wrapper components.

Opting-In with Lit

Lit uses a static class property for shadow root configuration. Adding delegatesFocus to LitElement’s config is easy:

export class AgButton extends LitElement {
  static shadowRootOptions = {
    ...LitElement.shadowRootOptions,
    delegatesFocus: true,
  };
}

Spreading LitElement.shadowRootOptions keeps Lit’s defaults intact. delegatesFocus is supported across major browsers and needs no polyfill.

When to Use It, and When Not To

Use delegatesFocus for simple wrapper components with a single focus target. It’s ideal for components like , , and .

Avoid it for components handling their own focus routing, like or those with multiple focus targets, like .

Avoid adding tabindex to the host with delegatesFocus. It causes navigation issues by creating redundant tab stops.

What We Changed in AgnosticUI

For AgnosticUI, delegatesFocus was applied only to AgButton, AgInput, and AgSelect. Changes included:

Adding shadowRootOptions:

static shadowRootOptions = {
  ...LitElement.shadowRootOptions,
  delegatesFocus: true,
};

Removing manual focus() and blur() overrides. These are unnecessary