Skip to content

feat: FocusScope custom restore focus target - #10962

Open
snowystinger wants to merge 1 commit into
mainfrom
focusscope-custom-restore-target
Open

snowystinger wants to merge 1 commit into
mainfrom
focusscope-custom-restore-target

Conversation

@snowystinger

Copy link
Copy Markdown
Member

Closes #9876
Taking over #10926 so we can iterate faster before release

Summary

📝 Test Instructions

Release impact

  • Only changes docs, tests, CI, or development tools. Nothing shipped to users changes.
  • Fixes a bug or improves existing code without changing how apps use it.
  • Adds a feature or API while keeping existing usage working.
  • May break existing usage or require changes in apps that use this code.

✅ PR Checklist

  • I followed the contributing guide.
  • I tested this change locally and included the results in Test Instructions, or explained why testing does not apply.
  • I understand and can explain every change in this PR. If I used AI assistance, I followed the AI contribution guidance.

🧢 Your Project

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown
## API Changes

react-aria-components

/react-aria-components:Modal

 Modal {
   children?: ChildrenOrFunction<ModalRenderProps>
   className?: ClassNameOrFunction<ModalRenderProps> = 'react-aria-ModalOverlay'
   defaultOpen?: boolean
   isDismissable?: boolean = false
   isEntering?: boolean
   isExiting?: boolean
   isKeyboardDismissDisabled?: boolean = false
   isOpen?: boolean
   onEnter?: (HTMLElement) => void | Promise<void>
   onExit?: (HTMLElement) => void | Promise<void>
   onOpenChange?: (boolean) => void
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, ModalRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   shouldCloseOnInteractOutside?: (Element) => boolean
   slot?: string | null
   style?: StyleOrFunction<ModalRenderProps>
 }

/react-aria-components:ModalOverlay

 ModalOverlay {
   children?: ChildrenOrFunction<ModalRenderProps>
   className?: ClassNameOrFunction<ModalRenderProps> = 'react-aria-ModalOverlay'
   defaultOpen?: boolean
   isDismissable?: boolean = false
   isEntering?: boolean
   isExiting?: boolean
   isKeyboardDismissDisabled?: boolean = false
   isOpen?: boolean
   onEnter?: (HTMLElement) => void | Promise<void>
   onExit?: (HTMLElement) => void | Promise<void>
   onOpenChange?: (boolean) => void
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, ModalRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   shouldCloseOnInteractOutside?: (Element) => boolean
   slot?: string | null
   style?: StyleOrFunction<ModalRenderProps>
 }

/react-aria-components:Popover

 Popover {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   arrowBoundaryOffset?: number = 0
   arrowRef?: RefObject<Element | null>
   boundaryElement?: Element = document.body
   children?: ChildrenOrFunction<PopoverRenderProps>
   className?: ClassNameOrFunction<PopoverRenderProps> = 'react-aria-Popover'
   containerPadding?: number = 12
   crossOffset?: number = 0
   defaultOpen?: boolean
   getTargetRect?: (Element) => DOMRectReadOnly | null | undefined = target.getBoundingClientRect()
   isEntering?: boolean
   isExiting?: boolean
   isKeyboardDismissDisabled?: boolean = false
   isNonModal?: boolean
   isOpen?: boolean
   maxHeight?: number
   offset?: number = 8
   onBlurWithin?: (FocusEvent) => void
   onFocusWithin?: (FocusEvent) => void
   onFocusWithinChange?: (boolean) => void
   onOpenChange?: (boolean) => void
   placement?: Placement = 'bottom'
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   scrollRef?: RefObject<Element | null> = overlayRef
   shouldCloseOnInteractOutside?: (Element) => boolean
   shouldFlip?: boolean = true
   shouldSkipAnimation?: boolean
   slot?: string | null
   style?: StyleOrFunction<PopoverRenderProps>
   trigger?: string
   triggerRef?: RefObject<Element | null>
 }

/react-aria-components:SheetOverlay

 SheetOverlay {
   children?: ChildrenOrFunction<SheetRenderProps>
   className?: ClassNameOrFunction<SheetRenderProps> = 'react-aria-SheetOverlay'
   defaultOpen?: boolean
   isOpen?: boolean
   onOpenChange?: (boolean) => void
   position?: 'bottom' | 'top' | 'left' | 'right' | 'start' | 'end' | 'center' = 'bottom'
   preventDismissal?: boolean = false
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, SheetRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   shouldCloseOnInteractOutside?: (Element) => boolean
   slot?: string | null
   snapPoints?: Array<number | string>
   style?: StyleOrFunction<SheetRenderProps>
 }

/react-aria-components:Sheet

 Sheet {
   children?: ChildrenOrFunction<SheetRenderProps>
   className?: ClassNameOrFunction<SheetRenderProps> = 'react-aria-Sheet'
   overscrollPadding?: boolean
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, SheetRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   slot?: string | null
   stackAnimation?: string
   style?: StyleOrFunction<SheetRenderProps>
   swipeAnimation?: string
     start?: number
   end?: number
 }
 }

/react-aria-components:ModalOverlayProps

 ModalOverlayProps {
   children?: ChildrenOrFunction<ModalRenderProps>
   className?: ClassNameOrFunction<ModalRenderProps> = 'react-aria-ModalOverlay'
   defaultOpen?: boolean
   isDismissable?: boolean = false
   isEntering?: boolean
   isExiting?: boolean
   isKeyboardDismissDisabled?: boolean = false
   isOpen?: boolean
   onEnter?: (HTMLElement) => void | Promise<void>
   onExit?: (HTMLElement) => void | Promise<void>
   onOpenChange?: (boolean) => void
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, ModalRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   shouldCloseOnInteractOutside?: (Element) => boolean
   slot?: string | null
   style?: StyleOrFunction<ModalRenderProps>
 }

/react-aria-components:PopoverProps

 PopoverProps {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   arrowBoundaryOffset?: number = 0
   arrowRef?: RefObject<Element | null>
   boundaryElement?: Element = document.body
   children?: ChildrenOrFunction<PopoverRenderProps>
   className?: ClassNameOrFunction<PopoverRenderProps> = 'react-aria-Popover'
   containerPadding?: number = 12
   crossOffset?: number = 0
   defaultOpen?: boolean
   getTargetRect?: (Element) => DOMRectReadOnly | null | undefined = target.getBoundingClientRect()
   isEntering?: boolean
   isExiting?: boolean
   isKeyboardDismissDisabled?: boolean = false
   isNonModal?: boolean
   isOpen?: boolean
   maxHeight?: number
   offset?: number = 8
   onBlurWithin?: (FocusEvent) => void
   onFocusWithin?: (FocusEvent) => void
   onFocusWithinChange?: (boolean) => void
   onOpenChange?: (boolean) => void
   placement?: Placement = 'bottom'
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   scrollRef?: RefObject<Element | null> = overlayRef
   shouldCloseOnInteractOutside?: (Element) => boolean
   shouldFlip?: boolean = true
   shouldSkipAnimation?: boolean
   slot?: string | null
   style?: StyleOrFunction<PopoverRenderProps>
   trigger?: string
   triggerRef?: RefObject<Element | null>
 }

/react-aria-components:SheetOverlayProps

 SheetOverlayProps {
   children?: ChildrenOrFunction<SheetRenderProps>
   className?: ClassNameOrFunction<SheetRenderProps> = 'react-aria-SheetOverlay'
   defaultOpen?: boolean
   isOpen?: boolean
   onOpenChange?: (boolean) => void
   position?: 'bottom' | 'top' | 'left' | 'right' | 'start' | 'end' | 'center' = 'bottom'
   preventDismissal?: boolean = false
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, SheetRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   shouldCloseOnInteractOutside?: (Element) => boolean
   slot?: string | null
   snapPoints?: Array<number | string>
   style?: StyleOrFunction<SheetRenderProps>
 }

/react-aria-components:SheetProps

 SheetProps {
   children?: ChildrenOrFunction<SheetRenderProps>
   className?: ClassNameOrFunction<SheetRenderProps> = 'react-aria-Sheet'
   overscrollPadding?: boolean
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, SheetRenderProps>
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   slot?: string | null
   stackAnimation?: string
   style?: StyleOrFunction<SheetRenderProps>
   swipeAnimation?: string
     start?: number
   end?: number
 }
 }

@react-aria/focus

/@react-aria/focus:FocusScope

 FocusScope {
   autoFocus?: boolean
   children: ReactNode
   contain?: boolean
-  restoreFocus?: boolean
+  restoreFocus?: boolean | RefObject<FocusableElement | null> | (Modality | null) => FocusableElement | boolean | null
 }

/@react-aria/focus:FocusScopeProps

 FocusScopeProps {
   autoFocus?: boolean
   children: ReactNode
   contain?: boolean
-  restoreFocus?: boolean
+  restoreFocus?: boolean | RefObject<FocusableElement | null> | (Modality | null) => FocusableElement | boolean | null
 }

@react-aria/overlays

/@react-aria/overlays:Overlay

 Overlay {
   children: ReactNode
   disableFocusManagement?: boolean
   isExiting?: boolean
   portalContainer?: Element = document.body
+  restoreFocus?: FocusScopeProps['restoreFocus'] = true
   shouldContainFocus?: boolean
 }

/@react-aria/overlays:OverlayProps

 OverlayProps {
   children: ReactNode
   disableFocusManagement?: boolean
   isExiting?: boolean
   portalContainer?: Element = document.body
+  restoreFocus?: FocusScopeProps['restoreFocus'] = true
   shouldContainFocus?: boolean
 }

@react-spectrum/ai

/@react-spectrum/ai:PromptTokenFieldPopoverProps

 PromptTokenFieldPopoverProps {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   arrowRef?: RefObject<Element | null>
   boundaryElement?: Element = document.body
   children?: ChildrenOrFunction<PopoverRenderProps>
   containerPadding?: number = 12
   crossOffset?: number = 0
   defaultOpen?: boolean
   filterAnchor?: Position | null
   getTargetRect?: (Element) => DOMRectReadOnly | null | undefined = target.getBoundingClientRect()
   hideArrow?: boolean = false
   isEntering?: boolean
   isExiting?: boolean
   isFocused?: boolean
   isNonModal?: boolean
   isOpen?: boolean
   items?: Array<React.ReactNode> | null | Promise<Array<React.ReactNode> | null>
   maxHeight?: number
   menuWidth?: number
   offset?: number = 8
   onBlurWithin?: (FocusEvent) => void
   onFocusWithin?: (FocusEvent) => void
   onFocusWithinChange?: (boolean) => void
   onOpenChange?: (boolean) => void
   placement?: Placement = 'bottom'
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   scrollRef?: RefObject<Element | null> = overlayRef
   shouldFlip?: boolean = true
   size?: 'S' | 'M' | 'L'
   slot?: string | null
   trigger?: string
   triggerRef?: RefObject<Element | null>
 }

@react-spectrum/s2

/@react-spectrum/s2:PopoverProps

 PopoverProps {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   arrowRef?: RefObject<Element | null>
   boundaryElement?: Element = document.body
   children?: ChildrenOrFunction<PopoverRenderProps>
   containerPadding?: number = 12
   crossOffset?: number = 0
   defaultOpen?: boolean
   getTargetRect?: (Element) => DOMRectReadOnly | null | undefined = target.getBoundingClientRect()
   hideArrow?: boolean = false
   isEntering?: boolean
   isExiting?: boolean
   isNonModal?: boolean
   isOpen?: boolean
   maxHeight?: number
   offset?: number = 8
   onBlurWithin?: (FocusEvent) => void
   onFocusWithin?: (FocusEvent) => void
   onFocusWithinChange?: (boolean) => void
   onOpenChange?: (boolean) => void
   placement?: Placement = 'bottom'
+  restoreFocus?: OverlayProps['restoreFocus'] = true
   scrollRef?: RefObject<Element | null> = overlayRef
   shouldFlip?: boolean = true
   size?: 'S' | 'M' | 'L'
   slot?: string | null
   trigger?: string
   triggerRef?: RefObject<Element | null>
 }

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown

Agent Skills Changes

Modified (17)
Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/dc08f0592d1210c1ddec381389e64589f3635833/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/dc08f0592d1210c1ddec381389e64589f3635833/

*
* @default true
*/
restoreFocus?: OverlayProps['restoreFocus'];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we omit this from SheetProps?

*
* @default true
*/
restoreFocus?: OverlayProps['restoreFocus'];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we omit this from S2's PopoverProps?

*
* @default true
*/
restoreFocus?: OverlayProps['restoreFocus'];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to use a named type alias instead so this renders better in the docs API table:

export type RestoreFocus =
  | boolean
  | RefObject<FocusableElement | null>
  | ((modality: Modality | null) => FocusableElement | boolean | null | undefined);

Right now it looks like this:

Screenshot 2026-11-13 at 5 00 47 PM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow customising focus restoration target when ModalOverlay trigger element is removed from DOM

3 participants