ShadowRoot: delegatesFocus property
The delegatesFocus
read-only property of the ShadowRoot
interface returns true
if the shadow root delegates focus, and false
otherwise.
If true
, when a non-focusable part of the shadow DOM is clicked, or .focus()
is called on the host element, the first focusable part 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 with tabindex="-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, the autofocus
attribute can be specified on the element which should receive initial focus. Use the autofocus
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 the delegatesFocus
property of the object passed to Element.attachShadow()
, or using the shadowrootdelegatesfocus
attribute of the <template>
element when a shadow root is created declaratively.
Value
true
if the shadow root delegates focus, and false
otherwise.
Examples
let customElem = document.querySelector("my-shadow-dom-element");
let shadow = customElem.shadowRoot;
// ...
// Does it delegate focus?
let hostElem = shadow.delegatesFocus;
The Declarative Shadow DOM with delegated focus example in the <template>
documentation demonstrates the effects of delegating focus.
Specifications
Specification |
---|
DOM Standard # shadowroot-delegates-focus |
Browser compatibility
BCD tables only load in the browser