fix(headless): keep pointer interactions from painting a focus ring

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,

.changeset/headless-return-focus.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/hooks/use-return-focus.test.ts

@@ -0,0 +1,98 @@
+import type { FloatingEvents } from '@floating-ui/react';
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useReturnFocus } from './use-return-focus';
+
+function createEvents(): FloatingEvents & { close: (event?: Event) => void } {
+ const handlers = new Map<string, Array<(data: unknown) => void>>();
+
+ return {
+ emit(event, data) {
+ handlers.get(event)?.forEach(handler => handler(data));
+ },
+ on(event, handler) {
+ handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+ },
+ off(event, handler) {
+ handlers.set(
+ event,
+ (handlers.get(event) ?? []).filter(h => h !== handler),
+ );
+ },
+ close(event) {
+ this.emit('openchange', { open: false, event });
+ },
+ };
+}
+
+function renderReturnFocus(trigger: HTMLElement) {
+ const events = createEvents();
+
+ const { result, rerender } = renderHook(
+ ({ open }: { open: boolean }) =>
+ useReturnFocus({ open, events, elements: { domReference: trigger, reference: trigger, floating: null } }),
+ { initialProps: { open: false } },
+ );
+
+ return { events, result, open: (open: boolean) => rerender({ open }) };
+}
+
+let trigger: HTMLElement;
+
+afterEach(() => trigger?.remove());
+
+describe('useReturnFocus', () => {
+ beforeEach(() => {
+ trigger = document.createElement('button');
+ document.body.append(trigger);
+ });
+
+ it('resolves to the trigger while open', () => {
+ const { result, open } = renderReturnFocus(trigger);
+
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from the keyboard', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new KeyboardEvent('keydown', { key: 'Escape' }));
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('keeps the trigger when the close came from a control inside the popup', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ // A Close button or menu item routes through the consumer's own state setter,
+ // so floating-ui reports the change with no event behind it.
+ events.close();
+
+ expect(result.current.current).toBe(trigger);
+ });
+
+ it('leaves focus alone when the close came from a pointer', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ expect(result.current.current).toBeNull();
+ });
+
+ it('restores the trigger on the next open', () => {
+ const { events, result, open } = renderReturnFocus(trigger);
+ open(true);
+ events.close(new MouseEvent('mousedown', { detail: 1 }));
+
+ open(false);
+ open(true);
+
+ expect(result.current.current).toBe(trigger);
+ });
+});

packages/headless/src/hooks/use-return-focus.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { FloatingContext } from '@floating-ui/react';
+import { useEffect, useRef } from 'react';
+
+import { isKeyboardEvent } from '../utils/interaction-modality';
+
+/**
+ * The element `FloatingFocusManager` restores focus to when the floating element closes.
+ *
+ * The trigger is the default, which is what a keyboard user needs. Safari never focuses a
+ * button it was clicked on, so after a pointer dismiss the popup is the only thing the page
+ * has focused: restoring focus to the trigger then matches `:focus-visible` and paints a ring
+ * the user never asked for. A pointer dismiss therefore resolves to `null`, which leaves focus
+ * where the pointer left it, the same choice Base UI makes from its close interaction type.
+ *
+ * Pass the result to `FloatingFocusManager`'s `returnFocus`. On `null` it falls back to the
+ * hidden guard element it keeps next to the trigger, so the tab position survives; verify that
+ * still holds when upgrading `@floating-ui/react`.
+ */
+export function useReturnFocus(
+ context: Pick<FloatingContext, 'open' | 'events' | 'elements'>,
+): React.MutableRefObject<HTMLElement | null> {
+ const { open, events, elements } = context;
+ const returnFocusRef = useRef<HTMLElement | null>(null);
+ const trigger = elements.domReference;
+
+ useEffect(() => {
+ if (open) {
+ returnFocusRef.current = trigger instanceof HTMLElement ? trigger : null;
+ }
+ }, [open, trigger]);
+
+ useEffect(() => {
+ // Closes routed straight through the consumer's own state setter (a Close button, an
+ // item click) never reach floating-ui, so only what floating-ui itself drives can
+ // downgrade the default.
+ function onOpenChange({ open, event }: { open: boolean; event?: Event }) {
+ if (!open && event && !isKeyboardEvent(event)) {
+ returnFocusRef.current = null;
+ }
+ }
+
+ events.on('openchange', onOpenChange);
+ return () => events.off('openchange', onOpenChange);
+ }, [events]);
+
+ return returnFocusRef;
+}

packages/headless/src/primitives/autocomplete/autocomplete.test.tsx

@@ -643,6 +643,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -786,6 +787,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);
@@ -880,6 +882,7 @@ describe('Autocomplete', () => {
 
  return (
  <Popover.Root
+ initialFocus='first'
  open={popoverOpen}
  onOpenChange={open => {
  setPopoverOpen(open);

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -11,6 +11,8 @@ export interface DialogContextValue {
  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
  labelId: string;
  descriptionId: string;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -12,8 +12,18 @@ export type DialogPopupProps = ComponentProps<'div'>;
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
  const { render, ...otherProps } = props;
- const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
- useDialogContext();
+ const {
+ popupRef,
+ refs,
+ getFloatingProps,
+ floatingContext,
+ modal,
+ returnFocusRef,
+ labelId,
+ descriptionId,
+ mounted,
+ transitionProps,
+ } = useDialogContext();
 
  const ownProps = {
  'aria-labelledby': labelId,
@@ -43,6 +53,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  context={floatingContext}
  modal={modal}
  outsideElementsInert={modal}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DialogContext, type DialogContextValue } from './dialog-context';
 
@@ -43,6 +44,8 @@ function DialogInner(props: DialogProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -65,6 +68,7 @@ function DialogInner(props: DialogProps) {
  getReferenceProps,
  getFloatingProps,
  popupRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -78,6 +82,7 @@ function DialogInner(props: DialogProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/drawer/drawer-popup.tsx

@@ -24,6 +24,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ returnFocusRef,
  labelId,
  descriptionId,
  mounted,
@@ -107,6 +108,7 @@ export const DrawerPopup = React.forwardRef<HTMLDivElement, DrawerPopupProps>(fu
  modal={modal}
  outsideElementsInert={modal}
  initialFocus={autoFocus ? undefined : popupRef}
+ returnFocus={returnFocusRef}
  >
  {element}
  </FloatingFocusManager>

packages/headless/src/primitives/drawer/drawer-root.tsx

@@ -14,6 +14,7 @@ import {
 import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { DrawerAttrs, DrawerCssVars, registerDrawerCssVars } from './css-vars';
 import {
@@ -119,6 +120,8 @@ function DrawerInner(props: DrawerProps) {
  onOpenChange: setOpen,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({ open, ref: popupRef });
 
  const click = useClick(floatingContext);
@@ -223,6 +226,7 @@ function DrawerInner(props: DrawerProps) {
  getFloatingProps,
  popupRef,
  backdropRef,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,
@@ -247,6 +251,7 @@ function DrawerInner(props: DrawerProps) {
  refs,
  getReferenceProps,
  getFloatingProps,
+ returnFocusRef,
  modal,
  labelId,
  descriptionId,

packages/headless/src/primitives/menu/menu-context.ts

@@ -24,6 +24,8 @@ export interface MenuContextValue {
  labelsRef: React.MutableRefObject<Array<string | null>>;
  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
  popupRef: React.RefObject<HTMLDivElement | null>;
+ /** Where focus goes when the menu closes, or `null` to leave focus alone. */
+ returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  isNested: boolean;
  mounted: boolean;
  transitionProps: TransitionProps;

packages/headless/src/primitives/menu/menu-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { useMenuContext } from './menu-context';
 
 export type MenuPositionerProps = ComponentProps<'div'>;
@@ -21,6 +21,7 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  elementsRef,
  labelsRef,
  isNested,
+ returnFocusRef,
  setActiveIndex,
  } = useMenuContext();
 
@@ -83,8 +84,8 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
  <FloatingFocusManager
  context={floatingContext}
  modal={false}
- initialFocus={isNested ? -1 : 0}
- returnFocus={!isNested}
+ initialFocus={isNested ? -1 : isKeyboardOpen(floatingContext) ? 0 : refs.floating}
+ returnFocus={isNested ? false : returnFocusRef}
  >
  <FloatingList
  elementsRef={elementsRef}

packages/headless/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
+import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
 import { MenuContext, type MenuContextValue } from './menu-context';
@@ -85,6 +86,8 @@ function MenuInner(props: MenuProps) {
  whileElementsMounted: autoUpdate,
  });
 
+ const returnFocusRef = useReturnFocus(floatingContext);
+
  const { mounted, transitionProps } = useTransition({
  open,
  ref: popupRef,
@@ -179,6 +182,7 @@ function MenuInner(props: MenuProps) {
  labelsRef,
  arrowRef,
  popupRef,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,
@@ -194,6 +198,7 @@ function MenuInner(props: MenuProps) {
  getFloatingProps,
  getItemProps,
  activeIndex,
+ returnFocusRef,
  isNested,
  mounted,
  transitionProps,