Overlay dismiss with VoiceOver on iOS

[SpasiboKojima]

I've tried ModalBottomSheet with and without nativeOverlay and I don't see a way to close the sheet by tapping overlay, only with custom placed buttons. Shouldn't it be focusable?

[patrickmichalik]

Hello! Thanks for raising this. Yes, an accessible dismissal path is needed. In addition to exposing the scrim to VoiceOver, we should implement accessibilityPerformEscape on the host, so the escape gesture dismisses the sheet as well. The equivalent should also be done on the Android side.

[andrea-martinez-dev]

In addition to exposing the scrim to VoiceOver, we should implement accessibilityPerformEscape on the host, so the escape gesture dismisses the sheet as well. The equivalent should also be done on the Android side.

@patrickmichalik I'd also expect the back Android gesture/button to close the ModalBottomSheet with TalkBack off, too.

EDIT: ..and with ESC key from an external keyboard too, which is also important for accessibility.

[andrea-martinez-dev]

@SpasiboKojima I'm not sure about the overlay being focusable, as the scrim is not part of the content, see ARIA Authoring Practices Guide.

So I'd definitely go with a custom placed button for that (an explicit Close at the bottom, a handle at the top, an X icon..), see also Material Design for some inspiration.

[falcondpr]

Hi! I'd like to work on this, following the direction outlined above. My plan:

iOS

• Expose the scrim (the UIControl in BottomSheetHostingView) to VoiceOver as a "Dismiss" button, but only while the sheet is modally presented with a non-programmatic close detent — exactly when tapping it would dismiss. Otherwise it stays out of the accessibility tree, so a scrim over a programmatic-only close detent remains decorative.
• Implement accessibilityPerformEscape on the hosting view, reusing the exact scrim-tap dismissal path (scrimDismissIndex → snapToIndex), returning false when there is nothing to dismiss so the gesture keeps bubbling.

Android

• The scrim is canvas-drawn, so I'd expose it as a virtual accessibility node via ExploreByTouchHelper (button role, same only-while-dismissible condition).
• Surface ACTION_DISMISS on the sheet container so TalkBack's dismiss action works while focus is inside the sheet content — the Android counterpart of accessibilityPerformEscape.

No JS or public-API changes. External-keyboard ESC (mentioned above) could be a follow-up.

One note on verification: I don't currently have a physical iOS device, so the VoiceOver side is verified with the Accessibility Inspector on the simulator for now — I'm working on getting a device to confirm the real VoiceOver flows. The Android side is verified on a physical Pixel 9.

Does this match what you had in mind?

[patrickmichalik]

@andrea-martinez-dev: Android-back and Escape handling are left to the consumer, since different kinds of behavior may be desired—especially with a programmatic closed detent. The consumer has the current index and can update it as they see fit in response to those inputs. In contrast, the accessibility paths under discussion would be difficult or impossible to implement reliably in consumer-side. Regarding scrim focusability, my initial instinct was similar, but it looks like the modal sheets in iOS system apps do expose their scrims as accessibility targets. Following that precedent seems like our best option.

@falcondpr, thanks for putting this together. I see you’ve already opened #56, so I’ll review it there.

[andrea-martinez-dev]

@patrickmichalik thanks for the explanation! Makes sense for programmatic detents.

I'd argue though that Android back and ESC for dismissing modals aren't just generic input handling—they're actually part of the accessibility requirements (ARIA modal pattern mandates ESC support). Similar to the accessibility paths you mentioned, this is something most consumers could struggle to implement consistently.

React Native's Modal component treats onRequestClose (back button) and ESC as a default modal behavior, not an optional consumer concern. It's wired into the platform expectations.

Would you consider making it the default behavior for ModalBottomSheet (matching both ARIA and RN Modal) while still allowing override for programmatic detent cases? That way most consumers get the right behavior out of the box, but you keep the flexibility when needed.

[patrickmichalik]

@andrea-martinez-dev, I think there are two separate concerns here: exposing the input and deciding what transition it should cause.

It’s true that Escape is not as straightforward for consumers as Android back, so there may be value in normalizing the two at the ModalBottomSheet level. However, React Native’s Modal does not itself dismiss in response to those inputs. It intercepts them and invokes onRequestClose; the consumer still decides whether and how to close the modal. If we followed that precedent, it would suggest exposing a similar request callback—not choosing a detent transition automatically.

The ARIA modal pattern is useful precedent for the expected keyboard interaction, but it doesn’t resolve the behavior of a controlled sheet with potentially different detent configurations and UX requirements. I don’t think there is a single “right behavior” we should impose by default and then require consumers to override.

I’d therefore be open to an onRequestClose-style API for consistently surfacing Android back and Escape, but I would keep the resulting behavior consumer-owned.

[andrea-martinez-dev]

@patrickmichalik An onRequestClose-style API would definitely help normalize back/ESC handling.

One side note: while you're right that React Native's Modal uses onRequestClose for the Android back button, the ESC key behavior is inconsistent at the moment: ESC dismisses the Modal even if onRequestClose isn't called or handled. This can lead to state desync—the Modal closes but your state still thinks it's open. I submitted an issue about it here sometime ago.

So if we go with an onRequestClose approach (which I think makes sense), it'd be important to ensure that both back and ESC are routed through it consistently.

[patrickmichalik]

Sounds good, @andrea-martinez-dev! Let’s track this addition separately, since it’s not strictly an accessibility mechanism. Could you create a dedicated issue?