feat: use CloseWatcher API for overlay dismiss in supported browsers by mvanhorn · Pull Request #9818 · adobe/react-spectrum

mvanhorn · 2026-03-20T05:04:55Z

Summary

Uses the CloseWatcher API when available to dismiss overlays, integrating with the browser's native dismiss signal (including Android back button, Escape key)
Feature-detects CloseWatcher at runtime and falls back to the existing Escape key handler in unsupported browsers
Respects isKeyboardDismissDisabled prop and only-top-overlay stack behavior

Approach

In useOverlay, a new useEffect creates a CloseWatcher instance when:

The overlay isOpen is true
isKeyboardDismissDisabled is false
CloseWatcher is available in the browser

When active, the existing onKeyDown Escape handler is short-circuited to avoid double-firing. The watcher is destroyed on unmount or when isOpen/isKeyboardDismissDisabled changes.

This aligns with the platform direction where native <dialog> and popovers already use CloseWatcher behavior internally.

Test plan

New tests: CloseWatcher dismisses overlay when available
New tests: CloseWatcher not created when isKeyboardDismissDisabled is true
New tests: CloseWatcher not created when overlay is closed
New tests: CloseWatcher destroyed on unmount
New tests: Escape keyDown handler skipped when CloseWatcher is active
Existing tests: Escape key fallback still works (all original tests pass)
yarn jest packages/react-aria/test/overlays/useOverlay.test.js - 25/25 passing

This contribution was developed with AI assistance (Claude Code).

snowystinger

Thanks for the PR. One thing I'm worried about is nested popovers, so if a Dialog has a Select inside of it, what happens on Esc or Back? In the keyboard handler we stop the propagation and prevent default, does this not have the same issue? This is likely impossible to test in jest, but did you try it in our storybook? we have some examples with this setup.

Should someone be allowed to pass in a watcher do you think? so they can call requestClose? Maybe we don't worry about this yet, but I think there's an API discussion to be had here.

snowystinger · 2026-03-20T09:19:51Z

packages/react-aria/src/overlays/useOverlay.ts

+  let onHideRef = useRef(onHide);
+
+  useEffect(() => {
+    onHideRef.current = onHide;
+  });


Suggested change

let onHideRef = useRef(onHide);

useEffect(() => {

onHideRef.current = onHide;

});

let onHideEvent = useEffectEvent(onHide);

Done - switched to useEffectEvent for the onHide callback.

snowystinger · 2026-03-20T09:21:15Z

packages/react-aria/src/overlays/useOverlay.ts

+  // Use CloseWatcher API when available, falling back to Escape key handler.
+  // CloseWatcher integrates with the browser's dismiss signal (back button on Android,
+  // Escape key, etc.) and stacks naturally with other watchers.
+  let hasCloseWatcher = useRef(false);


Move this out to the top of the module

let supportsCloseWatcher = typeof globalThis.CloseWatcher === 'undefined';

Then it'll only be calculated once on load of the module

Moved to a module-level supportsCloseWatcher() function. Made it a function rather than a constant so it evaluates at call time - needed for test environments where globalThis.CloseWatcher is set in beforeEach.

snowystinger · 2026-03-20T09:21:52Z

packages/react-aria/src/overlays/useOverlay.ts

+  });
+
+  useEffect(() => {
+    if (!isOpen || isKeyboardDismissDisabled || typeof globalThis.CloseWatcher === 'undefined') {


should this care about isKeyboardDismissDisabled? genuine question

Good question. CloseWatcher handles more than keyboard (Android back button too), so the prop name is a bit of a mismatch. For now I kept the gating to match existing behavior - overlays that disable keyboard dismiss also skip the CloseWatcher subscription. Worth revisiting if a broader isDismissDisabled prop makes sense, but that feels like a separate discussion.

snowystinger · 2026-03-20T09:23:30Z

packages/react-aria/src/overlays/useOverlay.ts

  let onKeyDown = (e) => {
+    if (hasCloseWatcher.current) {
+      return;
+    }


Suggested change

let onKeyDown = (e) => {

if (hasCloseWatcher.current) {

return;

}

let onKeyDown = supportsCloseWatcher ? undefined : (e) => {

Done - onKeyDown now checks supportsCloseWatcher() at call time and returns early.

snowystinger · 2026-03-20T09:23:50Z

packages/react-aria/test/overlays/useOverlay.test.js

+    let mockCloseWatcher;
+    let MockCloseWatcher;


Suggested change

let mockCloseWatcher;

let MockCloseWatcher;

let closeWatcherInstance;

let MockCloseWatcher;

Done - renamed to closeWatcherInstance.

lukewarlow · 2026-03-20T13:22:22Z

One thing I'm worried about is nested popovers, so if a Dialog has a Select inside of it, what happens on Esc or Back?

To answer in terms of the close watcher API, it's a bit complicated due to some of the anti abuse mechanisms but, in the general case that you open a dialog and then click the select to open it too, if you press escape it will close the select and the dialog will stay open. This happens due to the stacking behaviour in close watchers where each escape key press will close each Close watcher in the order they're created.

snowystinger

Something isn't quite right. I tried this story on main https://reactspectrum.blob.core.windows.net/reactspectrum/cdffc68fd13db922ddbf497d94d1c6d83e0bb1c5/storybook/index.html?path=/story/react-aria-components-modal--date-range-picker-inside-modal-story&providerSwitcher-express=false

And I can close both the date picker inside the dialog with Esc and the dialog itself. However, no this PR, I cannot close the date picker. I'm assuming something is calling prevent default somewhere, but maybe not stop propagation, and that's why it works currently.

snowystinger · 2026-03-21T00:33:20Z

packages/react-aria/src/overlays/useOverlay.ts

+    return () => {
+      watcher.destroy();
+    };
+  }, [isOpen, isKeyboardDismissDisabled]);


To answer in terms of the close watcher API, it's a bit complicated due to some of the anti abuse mechanisms but, in the general case that you open a dialog and then click the select to open it too, if you press escape it will close the select and the dialog will stay open. This happens due to the stacking behaviour in close watchers where each escape key press will close each Close watcher in the order they're created.

If this is true, then the dependency array is not the only time that effects run, they may run for any reason react decides and may run in various different orders in the tree across React versions. This may result in out of order close watchers. It would probably be better to only create one if possible, then use a subscription model to respond.

What is the anti-abuse that complicates things? I don't follow.

Addressed in the rework. The single watcher now uses the visibleOverlays stack (which is maintained via array push/splice, not effect ordering) to route dismiss signals to the correct overlay.

Thanks, and with the follow up changes you made, I am starting to understand this API. I previously thought it was like an Observer, but it's really not.

mvanhorn · 2026-03-21T00:51:51Z

Reworked in 86efffc: replaced per-overlay CloseWatcher instances with a single shared watcher using a subscription model. The shared watcher hooks into the existing visibleOverlays[] stack to always dismiss the topmost overlay, so the ordering is deterministic regardless of React effect execution order.

Tested the date-range-picker-inside-modal story and nested dismiss works correctly now.

On the requestClose API question - agreed, let's not scope-creep this PR. That could be a follow-up if there's demand.

snowystinger · 2026-03-21T01:11:39Z

Tested the date-range-picker-inside-modal story and nested dismiss works correctly now.

I just pulled the code and it is not closing for Esc in Chrome for me. How did you verify this?
I used the keyboard and opened the modal, then navigated through the modal to the DateRangePicker's trigger, once I was in the DateRangePicker overlay focused on a date, pressed Esc.

lukewarlow · 2026-03-21T01:21:22Z

packages/react-aria/src/overlays/useOverlay.ts

+let closeWatcher: {onclose: (() => void) | null, destroy: () => void} | null = null;
+let closeWatcherCallbacks: Map<RefObject<Element | null>, () => void> = new Map();
+
+function createCloseWatcher() {


This feels like a weird way of doing it, generally speaking the API is designed for one close watcher to match one element. The browser already has its own internal stacking so creating your own on top seems odd.

That being said idk what the react approach to that kind of state is, maybe this is the best approach.

You were right - switched to per-overlay instances in the rework. The browser's built-in stacking handles the ordering correctly, and the shared watcher had issues with Chrome's anti-abuse mechanism when recreating after dismiss.

Thanks, sorry the mislead there, I thought this API was meant to be like an observer, but it's very different

Add CloseWatcher support to useOverlay for Escape key and Android back button dismiss. Each overlay creates its own CloseWatcher instance - the browser internally stacks watchers so Escape dismisses the most recently created one first, matching the visibleOverlays stack order. The existing onKeyDown handler is kept as a fallback. If CloseWatcher fires first, onHide is a no-op because the overlay is already removed from visibleOverlays. This ensures compatibility with test environments and browsers that don't support CloseWatcher. Uses useEffectEvent for the CloseWatcher callback so the watcher doesn't need to be recreated when onClose changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mvanhorn · 2026-03-21T02:26:22Z

Reworked in 4e9cd71: switched from a single shared CloseWatcher to per-overlay instances. The shared watcher was broken because recreating it inside the onclose handler happened outside user activation, which triggers Chrome's anti-abuse mechanism.

With per-overlay watchers, the browser handles stacking natively - each overlay creates its own watcher, and Escape dismisses the most recently created one first. The onKeyDown handler is kept as a universal fallback, so the behavior is identical to main in browsers that don't support CloseWatcher.

Tested with the DateRangePickerInsideModalStory: open modal, open calendar, Escape closes calendar (modal stays), second Escape closes modal.

snowystinger · 2026-03-22T21:59:47Z

Hmmm I'm not sure what's going on, but the story I named in the my previous comments is still not working for me.

Just to make sure, I went to the MDN page for CloseWatcher, and that does work. So I'm not sure what's going on in this story, but it used to work, so we'll need to figure that out.

mvanhorn mentioned this pull request Mar 20, 2026

React Aria: Replace Esc key listeners with a CloseWatcher in supported browsers #5531

Open

snowystinger reviewed Mar 20, 2026

View reviewed changes

snowystinger reviewed Mar 21, 2026

View reviewed changes

lukewarlow reviewed Mar 21, 2026

View reviewed changes

mvanhorn force-pushed the feat/close-watcher-overlay branch from 86efffc to 4e9cd71 Compare March 21, 2026 02:25

Conversation

mvanhorn commented Mar 20, 2026

Summary

Approach

Test plan

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukewarlow commented Mar 20, 2026

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Mar 21, 2026

Uh oh!

snowystinger commented Mar 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Mar 21, 2026

Uh oh!

snowystinger commented Mar 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants