Improve focus management in shadow roots (#3794)

This PR improves the focus management when Headless UI components are
used inside of a shadow DOM.

We already tried to not use `document` directly, but instead rely on
`someKnownElement.ownerDocument` to get the correct document context.

This is unfortunately not enough, because if you have a focused element
_inside_ the shadow DOM, then `ownerDocument.activeElement` will return
the wrapping shadow DOM node and not the actual focused element inside
of the shadow DOM.

This PR improves that behavior by using `getRootNode()` instead and then
we read information such as the `activeElement` from there.

It's going to be easier if you look at this reproduction. The element
with the black border is a shadow DOM element. The `toggle` button is a
Popover button.

Expected behavior:

1. You can tab through the elements in order from outside the shadow DOM
into the shadow DOM and out again.
1. You can shift+tab in reverse order as well.
1. When the Popover is open, pressing `Escape` should close the Popover.
1. When tabbing outside of the open popover, the popover should close.

Let's see these things in action:

---

1. Pressing escape on an open Popover should close it

**before:**


https://github.com/user-attachments/assets/99ff5768-f6ac-490f-a607-391bbdd21d65


The reason it doesn't is because we check the `activeElement`, and we
only close the popover if it is the active element. But if you look at
devtools, the button is not the active element so therefore it doesn't
work.

**after:**


https://github.com/user-attachments/assets/22511835-98d3-452d-baac-447fa4e5a5e7

---

2. Tabbing out of an open popover with <kbd>Tab</kbd> should close the
Popover and focus the next element.

**before:**


https://github.com/user-attachments/assets/ab2c5849-f524-436b-aa7c-9e65e5debc67

Here it does all the wrong things, it doesn't go into the PopoverPanel,
it doesn't go to the next button, but it goes to the next button
_outside_ of the shadow dom.

**after:**


https://github.com/user-attachments/assets/c5f653f1-338d-41c4-a166-735e6c1d1435

---

## Test plan

1. Existing code still passes (we don't have shadow DOM tests)
2. Tested the behavior from the reproduction and it all works as
expected now:


https://github.com/user-attachments/assets/a90206e6-ae5e-4748-a4e4-c65dfa69d8f6


Fixes: #2951

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Improve focus management in shadow DOM roots ([#3794](https://github.com/tailwindlabs/headlessui/pull/3794))
 
 ## [2.2.8] - 2025-09-12
 

packages/@headlessui-react/src/components/combobox/combobox.tsx

@@ -67,6 +67,7 @@ import { Focus } from '../../utils/calculate-active-index'
 import { disposables } from '../../utils/disposables'
 import * as DOM from '../../utils/dom'
 import { match } from '../../utils/match'
+import { isActiveElement } from '../../utils/owner'
 import { isMobile } from '../../utils/platform'
 import {
   RenderFeatures,
@@ -543,16 +544,13 @@ function InputFn<
     ...theirProps
   } = props
 
-  let [inputElement] = useSlice(machine, (state) => [state.inputElement])
-
   let internalInputRef = useRef<HTMLInputElement | null>(null)
   let inputRef = useSyncRefs(
     internalInputRef,
     ref,
     useFloatingReference(),
     machine.actions.setInputElement
   )
-  let ownerDocument = useOwnerDocument(inputElement)
 
   let [comboboxState, isTyping] = useSlice(machine, (state) => [
     state.comboboxState,
@@ -628,7 +626,7 @@ function InputFn<
         // Bail when the input is not the currently focused element. When it is not the focused
         // element, and we call the `setSelectionRange`, then it will become the focused
         // element which may be unwanted.
-        if (ownerDocument?.activeElement !== input) return
+        if (isActiveElement(input)) return
 
         let { selectionStart, selectionEnd } = input
 
@@ -642,7 +640,7 @@ function InputFn<
         input.setSelectionRange(input.value.length, input.value.length)
       })
     },
-    [currentDisplayValue, comboboxState, ownerDocument, isTyping]
+    [currentDisplayValue, comboboxState, isTyping]
   )
 
   // Trick VoiceOver in behaving a little bit better. Manually "resetting" the input makes VoiceOver

packages/@headlessui-react/src/components/dialog/dialog.tsx

@@ -160,7 +160,7 @@ let InternalDialog = forwardRefWithAs(function InternalDialog<
   let internalDialogRef = useRef<HTMLElement | null>(null)
   let dialogRef = useSyncRefs(internalDialogRef, ref)
 
-  let ownerDocument = useOwnerDocument(internalDialogRef)
+  let ownerDocument = useOwnerDocument(internalDialogRef.current)
 
   let dialogState = open ? DialogStates.Open : DialogStates.Closed
 

packages/@headlessui-react/src/components/disclosure/disclosure.tsx

@@ -206,7 +206,7 @@ function DisclosureFn<TTag extends ElementType = typeof DEFAULT_DISCLOSURE_TAG>(
   let close = useEvent(
     (focusableElement?: HTMLOrSVGElement | MutableRefObject<HTMLOrSVGElement | null>) => {
       dispatch({ type: ActionTypes.CloseDisclosure })
-      let ownerDocument = getOwnerDocument(internalDisclosureRef)
+      let ownerDocument = getOwnerDocument(internalDisclosureRef.current)
       if (!ownerDocument) return
       if (!buttonId) return
 

packages/@headlessui-react/src/components/focus-trap/focus-trap.tsx

@@ -25,6 +25,7 @@ import * as DOM from '../../utils/dom'
 import { Focus, FocusResult, focusElement, focusIn } from '../../utils/focus-management'
 import { match } from '../../utils/match'
 import { microTask } from '../../utils/micro-task'
+import { isActiveElement } from '../../utils/owner'
 import { forwardRefWithAs, useRender, type HasDisplayName, type RefProp } from '../../utils/render'
 
 type Containers =
@@ -108,7 +109,7 @@ function FocusTrapFn<TTag extends ElementType = typeof DEFAULT_FOCUS_TRAP_TAG>(
     features = FocusTrapFeatures.None
   }
 
-  let ownerDocument = useOwnerDocument(container)
+  let ownerDocument = useOwnerDocument(container.current)
 
   useRestoreFocus(features, { ownerDocument })
   let previousActiveElement = useInitialFocus(features, {
@@ -288,7 +289,7 @@ function useRestoreFocus(
   useWatch(() => {
     if (enabled) return
 
-    if (ownerDocument?.activeElement === ownerDocument?.body) {
+    if (isActiveElement(ownerDocument?.body)) {
       focusElement(getRestoreElement())
     }
   }, [enabled])

packages/@headlessui-react/src/components/listbox/listbox.tsx

@@ -71,7 +71,7 @@ import {
 } from '../../utils/focus-management'
 import { attemptSubmit } from '../../utils/form'
 import { match } from '../../utils/match'
-import { getOwnerDocument } from '../../utils/owner'
+import { isActiveElement } from '../../utils/owner'
 import {
   RenderFeatures,
   forwardRefWithAs,
@@ -666,7 +666,7 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
     let container = optionsElement
     if (!container) return
     if (listboxState !== ListboxStates.Open) return
-    if (container === getOwnerDocument(container)?.activeElement) return
+    if (isActiveElement(container)) return
 
     container?.focus({ preventScroll: true })
   }, [listboxState, optionsElement])

packages/@headlessui-react/src/components/menu/menu.tsx

@@ -60,6 +60,7 @@ import {
   restoreFocusIfNecessary,
 } from '../../utils/focus-management'
 import { match } from '../../utils/match'
+import { isActiveElement } from '../../utils/owner'
 import {
   RenderFeatures,
   forwardRefWithAs,
@@ -453,10 +454,10 @@ function ItemsFn<TTag extends ElementType = typeof DEFAULT_ITEMS_TAG>(
     let container = localItemsElement
     if (!container) return
     if (menuState !== MenuState.Open) return
-    if (container === ownerDocument?.activeElement) return
+    if (isActiveElement(container)) return
 
     container.focus({ preventScroll: true })
-  }, [menuState, localItemsElement, ownerDocument])
+  }, [menuState, localItemsElement])
 
   useTreeWalker(menuState === MenuState.Open, {
     container: localItemsElement,

packages/@headlessui-react/src/components/popover/popover-machine.ts

@@ -4,6 +4,7 @@ import { stackMachines } from '../../machines/stack-machine'
 import * as DOM from '../../utils/dom'
 import { getFocusableElements } from '../../utils/focus-management'
 import { match } from '../../utils/match'
+import { getOwnerDocument } from '../../utils/owner'
 
 type MouseEvent<T> = Parameters<MouseEventHandler<T>>[0]
 
@@ -142,10 +143,12 @@ export class PopoverMachine extends Machine<State, Actions> {
       if (!state.button) return false
       if (!state.panel) return false
 
+      let ownerDocument = getOwnerDocument(state.button) ?? document
+
       // We are part of a different "root" tree, so therefore we can consider it portalled. This is a
       // heuristic because 3rd party tools could use some form of portal, typically rendered at the
       // end of the body but we don't have an actual reference to that.
-      for (let root of document.querySelectorAll('body > *')) {
+      for (let root of ownerDocument.querySelectorAll('body > *')) {
         if (Number(root?.contains(state.button)) ^ Number(root?.contains(state.panel))) {
           return true
         }
@@ -157,7 +160,7 @@ export class PopoverMachine extends Machine<State, Actions> {
       // portalled or not because we can follow the default tab order. But if they
       // are not, then we can consider it being portalled so that we can ensure
       // that tab and shift+tab (hopefully) go to the correct spot.
-      let elements = getFocusableElements()
+      let elements = getFocusableElements(ownerDocument)
       let buttonIdx = elements.indexOf(state.button)
 
       let beforeIdx = (buttonIdx + elements.length - 1) % elements.length

packages/@headlessui-react/src/components/popover/popover.tsx

@@ -28,7 +28,7 @@ import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
 import { useLatestValue } from '../../hooks/use-latest-value'
 import { useOnDisappear } from '../../hooks/use-on-disappear'
 import { useOutsideClick } from '../../hooks/use-outside-click'
-import { useOwnerDocument } from '../../hooks/use-owner'
+import { useOwnerDocument, useRootDocument } from '../../hooks/use-owner'
 import { useResolveButtonType } from '../../hooks/use-resolve-button-type'
 import {
   MainTreeProvider,
@@ -70,7 +70,7 @@ import {
 } from '../../utils/focus-management'
 import { match } from '../../utils/match'
 import { microTask } from '../../utils/micro-task'
-import { getOwnerDocument } from '../../utils/owner'
+import { getActiveElement, getRootNode } from '../../utils/owner'
 import {
   RenderFeatures,
   forwardRefWithAs,
@@ -156,7 +156,7 @@ function PopoverFn<TTag extends ElementType = typeof DEFAULT_POPOVER_TAG>(
     }, [])
   )
 
-  let ownerDocument = useOwnerDocument(internalPopoverRef.current ?? button)
+  let rootDocument = useRootDocument(internalPopoverRef.current ?? button)
 
   let buttonIdRef = useLatestValue(buttonId)
   let panelIdRef = useLatestValue(panelId)
@@ -173,11 +173,11 @@ function PopoverFn<TTag extends ElementType = typeof DEFAULT_POPOVER_TAG>(
   let groupContext = usePopoverGroupContext()
   let registerPopover = groupContext?.registerPopover
   let isFocusWithinPopoverGroup = useEvent(() => {
+    let activeElement = getActiveElement(internalPopoverRef.current ?? button)
+
     return (
       groupContext?.isFocusWithinPopoverGroup() ??
-      (ownerDocument?.activeElement &&
-        (button?.contains(ownerDocument.activeElement) ||
-          panel?.contains(ownerDocument.activeElement)))
+      (activeElement && (button?.contains(activeElement) || panel?.contains(activeElement)))
     )
   })
 
@@ -204,7 +204,7 @@ function PopoverFn<TTag extends ElementType = typeof DEFAULT_POPOVER_TAG>(
 
   // Handle focus out
   useEventListener(
-    ownerDocument?.defaultView,
+    rootDocument,
     'focus',
     (event) => {
       if (event.target === window) return
@@ -392,7 +392,6 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
     })
   )
   let withinPanelButtonRef = useSyncRefs(internalButtonRef, ref)
-  let ownerDocument = useOwnerDocument(internalButtonRef)
 
   let handleKeyDown = useEvent((event: ReactKeyboardEvent<HTMLButtonElement>) => {
     if (isWithinPanel) {
@@ -426,10 +425,8 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
             return closeOthers?.(machine.state.buttonId!)
           }
           if (!internalButtonRef.current) return
-          if (
-            ownerDocument?.activeElement &&
-            !internalButtonRef.current.contains(ownerDocument.activeElement)
-          ) {
+          let activeElement = getActiveElement(internalButtonRef.current)
+          if (activeElement && !internalButtonRef.current.contains(activeElement)) {
             return
           }
           event.preventDefault()
@@ -535,7 +532,9 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
 
       if (result === FocusResult.Error) {
         focusIn(
-          getFocusableElements().filter((el) => el.dataset.headlessuiFocusGuard !== 'true'),
+          getFocusableElements(getRootNode(machine.state.button)).filter(
+            (el) => el.dataset.headlessuiFocusGuard !== 'true'
+          ),
           match(direction.current, {
             [TabDirection.Forwards]: Focus.Next,
             [TabDirection.Backwards]: Focus.Previous,
@@ -749,7 +748,7 @@ function PanelFn<TTag extends ElementType = typeof DEFAULT_PANEL_TAG>(
     setLocalPanelElement
   )
   let portalOwnerDocument = useOwnerDocument(button)
-  let ownerDocument = useOwnerDocument(internalPanelRef)
+  let ownerDocument = useOwnerDocument(internalPanelRef.current)
 
   useIsoMorphicEffect(() => {
     machine.actions.setPanelId(id)
@@ -777,10 +776,8 @@ function PanelFn<TTag extends ElementType = typeof DEFAULT_PANEL_TAG>(
       case Keys.Escape:
         if (machine.state.popoverState !== PopoverStates.Open) return
         if (!internalPanelRef.current) return
-        if (
-          ownerDocument?.activeElement &&
-          !internalPanelRef.current.contains(ownerDocument.activeElement)
-        ) {
+        let activeElement = getActiveElement(internalPanelRef.current)
+        if (activeElement && !internalPanelRef.current.contains(activeElement)) {
           return
         }
         event.preventDefault()
@@ -807,7 +804,7 @@ function PanelFn<TTag extends ElementType = typeof DEFAULT_PANEL_TAG>(
     if (popoverState !== PopoverStates.Open) return
     if (!internalPanelRef.current) return
 
-    let activeElement = ownerDocument?.activeElement as HTMLElement
+    let activeElement = getActiveElement(internalPanelRef.current)
     if (internalPanelRef.current.contains(activeElement)) return // Already focused within Dialog
 
     focusIn(internalPanelRef.current, Focus.First)
@@ -889,7 +886,8 @@ function PanelFn<TTag extends ElementType = typeof DEFAULT_PANEL_TAG>(
         [TabDirection.Forwards]: () => {
           if (!machine.state.button) return
 
-          let elements = getFocusableElements()
+          let root = getRootNode(machine.state.button) ?? document.body
+          let elements = getFocusableElements(root)
 
           let idx = elements.indexOf(machine.state.button)
           let before = elements.slice(0, idx + 1)
@@ -1015,17 +1013,17 @@ function GroupFn<TTag extends ElementType = typeof DEFAULT_GROUP_TAG>(
   })
 
   let isFocusWithinPopoverGroup = useEvent(() => {
-    let ownerDocument = getOwnerDocument(internalGroupRef)
-    if (!ownerDocument) return false
-    let element = ownerDocument.activeElement
+    let root = getRootNode(internalGroupRef.current)
+    if (!root) return false
+    let activeElement = getActiveElement(internalGroupRef.current)
 
-    if (internalGroupRef.current?.contains(element)) return true
+    if (internalGroupRef.current?.contains(activeElement)) return true
 
     // Check if the focus is in one of the button or panel elements. This is important in case you are rendering inside a Portal.
     return popovers.some((bag) => {
       return (
-        ownerDocument!.getElementById(bag.buttonId.current!)?.contains(element) ||
-        ownerDocument!.getElementById(bag.panelId.current!)?.contains(element)
+        root!.getElementById(bag.buttonId.current!)?.contains(activeElement) ||
+        root!.getElementById(bag.panelId.current!)?.contains(activeElement)
       )
     })
   })

packages/@headlessui-react/src/components/portal/portal.tsx

@@ -89,7 +89,7 @@ let InternalPortalFn = forwardRefWithAs(function InternalPortalFn<
     }),
     ref
   )
-  let defaultOwnerDocument = useOwnerDocument(internalPortalRootRef)
+  let defaultOwnerDocument = useOwnerDocument(internalPortalRootRef.current)
   let ownerDocument = incomingOwnerDocument ?? defaultOwnerDocument
   let target = usePortalTarget(ownerDocument)
   let parent = useContext(PortalParentContext)