HTML shadowrootdelegatesfocus Attribute

HTML shadowrootdelegatesfocus Attribute

The HTML shadowrootdelegatesfocus attribute is a boolean attribute used with a declarative shadow DOM <template>. When present with shadowrootmode, it sets the resulting shadow root to delegate focus to a focusable element within the shadow tree.

Elements That Use the shadowrootdelegatesfocus Attribute

The shadowrootdelegatesfocus attribute is used with the <template> element when declaring a shadow root.

Boolean Attribute

The shadowrootdelegatesfocus attribute is a boolean attribute. Its presence sets the delegatesFocus property of the shadow root created from the declarative shadow DOM template to true. When omitted, the value defaults to false.

<template shadowrootmode="open" shadowrootdelegatesfocus>
  <input type="text">
</template>

Because it is a boolean attribute, the presence of shadowrootdelegatesfocus is what matters. It does not need a value such as true or false.

How shadowrootdelegatesfocus Works

When focus delegation is enabled, focusing the shadow host can move focus to a focusable element inside the shadow tree. Clicking a non-focusable part of the shadow tree can also cause focus to move to a focusable element within the shadow tree.

<div>
  <template shadowrootmode="open" shadowrootdelegatesfocus>
    <p>Account Information</p>
    <input type="text" placeholder="Your name">
  </template>
</div>

In this example, the shadow root has focus delegation enabled. When focus is delegated into the shadow tree, the input can receive focus as its focusable target.

Using shadowrootdelegatesfocus with shadowrootmode

The shadowrootdelegatesfocus attribute does not create a shadow root by itself. It is used with a valid shadowrootmode="open" or shadowrootmode="closed" attribute on the same <template>.

<div>
  <template
    shadowrootmode="open"
    shadowrootdelegatesfocus>
    <input type="text" placeholder="Enter your name">
  </template>
</div>

The shadowrootmode attribute declares the shadow root, while shadowrootdelegatesfocus sets its focus delegation behavior.

Focus Behavior

When a shadow root delegates focus, calling focus() on the host or interacting with a non-focusable part of the shadow tree can delegate focus to a focusable element inside the shadow tree. The shadow host also receives applicable :focus styling while focus is delegated within the shadow tree.

By default, focus is delegated to the first focusable element found using the browser's focus delegation rules. If another element should receive the initial focus instead, the autofocus attribute can be used carefully to identify that element.

<template shadowrootmode="open" shadowrootdelegatesfocus>
  <button type="button">Close</button>
  <input type="text" autofocus placeholder="Enter your name">
</template>

Here, the autofocus attribute identifies the text field as the preferred focus target rather than relying on the first focusable element in the shadow tree.

Accessibility

Focus behavior is especially important for keyboard users and people using assistive technologies. Make sure that delegated focus moves to a useful and expected interactive element.

The first focusable element is not always the best place to begin interaction. For example, a close button might appear before the main form control in the shadow tree. Structure the component's focus order carefully and use autofocus only when automatically moving focus to a particular control is appropriate.

Do not use focus delegation as a replacement for a logical keyboard navigation order. Interactive controls inside the shadow tree should remain understandable and usable when navigating with the keyboard.

Common Mistakes

Do not use shadowrootdelegatesfocus without a valid shadowrootmode attribute when you intend to create a declarative shadow root. The attribute does not create a shadow root by itself.

Do not write shadowrootdelegatesfocus="false" to disable focus delegation. Because it is a boolean attribute, its presence enables the behavior. Omit the attribute when focus should not be delegated.

Do not assume that focus delegation makes every element inside the shadow tree focusable. Focus can only be moved to an element that can receive focus.

Do not assume that the first focusable element is always the most appropriate focus target. Consider the expected keyboard interaction and accessibility of the component when designing its focus order.

Browser Support

Baseline: Newly available indicates that a feature is supported in the latest stable version of each of the core browsers. Most users can use these features reliably, but they may not work in older browser versions.

The shadowrootdelegatesfocus attribute on the <template> element is supported in the latest core browser versions, but older browser versions may not support declarative focus delegation.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the shadowrootdelegatesfocus Attribute

The example creates an open declarative shadow root with focus delegation enabled. Click the component outside the input field to see focus delegated to the input in supporting browsers.

Summary

The HTML shadowrootdelegatesfocus attribute is a boolean attribute used with a declarative shadow DOM <template>. When combined with a valid shadowrootmode attribute, it sets the resulting shadow root's delegatesFocus property to true. This allows focus on the host or interaction with non-focusable shadow content to delegate focus to a focusable element within the shadow tree.