ExperimentalThe caller's ref and onCloseAutoFocus for the Radix Content. Both still work:
the ref receives the element too, and the caller's handler runs first and can itself prevent
the default.
ref: ref callback to attach to the surface's content element. The element is null
while the surface is closed, which makes the blur a no-op. Its identity is stable unless
props.ref changes. onCloseAutoFocus: handler to pass to the content. Spread both onto the
Radix Content.
This export is unstable and may change shape or disappear without notice
Close-auto-focus handler for the Radix Content; also calls the caller's handler
Ref callback for the Radix Content; also forwards the caller's ref
Treats the window losing focus as a press outside the calling surface, so an open menu or popover dismisses itself.
Web views are iframes, so a click in another web view, or in another application, never produces a
pointerdownin this document and Radix's outside-press detection never runs. Native menus close when their application is deactivated; this hook gives Radix surfaces the same behavior. From mount until unmount, abluronwindowdispatches a syntheticpointerdownon the content's parent element. A closed surface has no content node (unmounted) or a content node markeddata-state="closed"(animating out), and the blur is ignored in both cases, so a mounted-but-closed surface never presses on an unrelated open layer. Radix'sDismissableLayerlistens forpointerdownon the owner document and does not checkisTrusted, so the event takes its normal outside-press path:onPointerDownOutsideruns and can callpreventDefault()to keep the surface open, and a surface whoseopenis controlled without anonOpenChangestays open.The press lands "outside this surface, but inside whatever hosts it". A popover portaled into a dialog (via
PopoverPortalContainerProvider) closes while the dialog's ownDismissableLayersees an inside press and stays open. A popover or menu portaled todocument.bodyis pressed on from its own Radix popper wrapper (data-radix-popper-content-wrapper, whatparentElementresolves to there), which is outside it. A modal menu opened from inside a dialog is protected by Radix anyway: a layer below the top-most layer that disables outside pointer events does not dismiss.Focus rule: a dismissal caused by a click into another frame does not return focus to the trigger. The user has already put focus somewhere else, and Radix's default close-auto-focus would pull it back: a menu closing in one frame by returning focus to its trigger blurs the main window, which would close the menu the user just opened in another frame. The returned
onCloseAutoFocuscallspreventDefault()per shouldSuppressFocusReturn: when the active element is an<iframe>(the user clicked into a web view from this document), or when this window is a web view whose document has lost focus (the user clicked into another frame, or switched applications). In the main document a lostdocument.hasFocus()can only mean the OS window was deactivated, so the hook focuses the trigger itself and prevents Radix's default. After an outside interaction, which the synthetic press is, the non-modal Popover and the Menubar would skip their own restore, while a modal DropdownMenu would restore anyway; the outcome is the same for all three. The trigger is the element whosearia-controlsnames the content'sid, looked up at close and, failing that, as found when the content mounted; else the element the content'saria-labelledbynames. A surface without either (a context menu) restores nothing. Focus is never taken from an element the user focused elsewhere. Any other close, such as Escape or a click elsewhere in this document, restores focus as usual. The rule reads state at close time rather than remembering that a blur dismissal happened: Radix runs close-auto-focus from its own timer after an asynchronous unmount, so a flag cleared by a timeout loses that race under load.The synthetic press is untrusted and carries a window-blur marker (checked by the internal
isWindowBlurPress). The focus modality tracker and the overlay service's press recorder skip it, and the overlay service's own surfaces ignore it. Window service gesture tracking, the content-zoom bootstrap and the editor's selection snapshot see it and were judged benign. Another document-levelpointerdownlistener that must ignore it can check the marker the same way.Hidden-view case (the repo's rule on hidden views): a keyboard tab switch can hide a pane that holds an open menu. The blur listener then dismisses it on the next window blur, which is harmless, so there is deliberately no catch-up logic. The one deliberate exception is a non-modal compact
BookChapterControl: itsonInteractOutsideprevents this hook's synthetic press from dismissing it, so it stays open while its tab is hidden and closes through its trigger once the tab is visible again, or on Escape with focus in it.