ShadowRoot: delegatesFocus property

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since November 2021.

ThedelegatesFocus read-only property of theShadowRoot interface returnstrue if the shadow root delegates focus, andfalse otherwise.

Iftrue, when a non-focusable part of the shadow DOM is clicked, or.focus() is called on the host element, the first focusable part inside the host's shadow DOM is given focus, and the shadow host is given any available:focus styling.

Focus is of particular importance for keyboard users (including those using screen readers).delegatesFocus default behavior is to focus the first focusable element — which may be undesirable if that element is not meant to be part of the tabbing order (for example, an element withtabindex="-1"), or if a more 'important' focusable element should receive initial focus (for instance, the first text field rather than the 'close' button which precedes it). In such cases, theautofocus attribute can be specified on the element which should receive initial focus. Use theautofocus attribute with caution as it can introduce accessibility issues, such as bypassing important content which may go unnoticed due to focus being set to an element later in the DOM order.

The property value is originally set using thedelegatesFocus property of the object passed toElement.attachShadow(), or using theshadowrootdelegatesfocus attribute of the<template> element when a shadow root is created declaratively.

Value

true if the shadow root delegates focus, andfalse otherwise.

Examples

const customElem = document.querySelector("my-shadow-dom-element");const shadow = customElem.shadowRoot;// …// Does it delegate focus?const hostElem = shadow.delegatesFocus;

TheDeclarative Shadow DOM with delegated focus example in the<template> documentation demonstrates the effects of delegating focus.