feat(iOS, FormSheet v5): Add support for backgroundComponent#4100
feat(iOS, FormSheet v5): Add support for backgroundComponent#4100t0maboro wants to merge 1 commit into
Conversation
t0maboro
requested review from
LKuchno,
Copilot,
kkafar,
kligarski,
kmichalikk and
sgaczol
t0maboro
force-pushed
the
@t0maboro/formsheet-background-component
branch
from
561d8d8 to
6176a76
Compare
t0maboro
force-pushed
the
@t0maboro/fit-to-contents
branch
from
e3558da to
6121c7d
Compare
t0maboro
force-pushed
the
@t0maboro/formsheet-background-component
branch
from
6176a76 to
7fbdaf2
Compare
LKuchno
left a comment
LKuchno
left a comment
There was a problem hiding this comment.
Let's wait with updating the 'Expected' sections of the scenarios until the team discussion, so we can decide which approach we want to follow.
|
|
||
| ## E2E test | ||
|
|
||
| Other: Planned, but will be implemented separately. |
There was a problem hiding this comment.
Following new naming (described in RFC), if we are planning to implement e2e test I would change this line to:
| Other: Planned, but will be implemented separately. | |
| TBD: Planned, but will be implemented separately. |
| - [ ] Expected: The FormSheet opens smoothly. | ||
| - [ ] Expected: The background is the default system color (e.g., white or dark depending on the theme). |
There was a problem hiding this comment.
I don't think we should duplicate the Expected field. We could either combine both points into a single sentence, or list them as bullets under one Expected label, like this:
- Expected:
- The FormSheet opens smoothly.
- The background is the default system color (e.g., white or dark depending on the theme).
OR
Expected:
- The FormSheet opens smoothly.
- The background is the default system color (e.g., white or dark depending on the theme).
Either way, I think we should align on one convention as a team so we have a clear reference going forward.
There was a problem hiding this comment.
We will follow the second approach and omit "Expected:". It is redundant, as we can assume that any checkbox under a step represents the expected behavior to be verified.
There was a problem hiding this comment.
Agreed structure updated in scenario.md file 0afd645 and RFC https://github.com/software-mansion/react-native-screens-labs/pull/1493/changes/50448fce2fd1447f826c07d036f09a9a53c80fcb
| * This component must be positioned absolutely to fill the entire bounds of the native | ||
| * sheet, including the bottom safe area provided by UIKit. It renders behind the `children`. | ||
| * Useful for adding custom background components that should extend to the very bottom | ||
| * edge of the sheet, bypassing the `fitToContents` height restrictions. | ||
| * |
There was a problem hiding this comment.
Let's maybe add information that pointer events are disabled for this view.
| * | ||
| * @platform ios | ||
| */ | ||
| backgroundComponent?: React.ReactNode | undefined; |
There was a problem hiding this comment.
Should we use same render callback pattern as for header subviews?
| - [ ] Expected: The FormSheet opens smoothly. | ||
| - [ ] Expected: A navy background is visible behind the text content. | ||
| - [ ] Expected: A thin green bar is visible at the top edge. | ||
| - [ ] Expected: A red bar is visible at the very bottom edge of the screen, successfully rendering underneath the navigation bar. |
There was a problem hiding this comment.
The navigation bar disappears after some time so referencing it here might be a bit confusing.
Description
This PR introduces the backgroundComponent prop to the iOS
FormSheet. It allows rendering custom backgrounds that stretch to the native bounds of the modal.When using
detents="fitToContents", the React content wrapper inherently calculates its height based purely on its children. However, UIKit automatically appends the bottom safe area to the sheet's bounds. Previously, this meant the React content would end above the Home Indicator, leaving the uncollapsible safe area unstyled.Important
Some components having a custom (or asynchronous) layout logic may not work properly with synchronous state updates that we're adapting for FormSheet, e.g.
Imagecomponent fromreact-nativedoesn't work well, while 3p libs implementations are more resilient for working with synchronous updates.Screen.Recording.2026-05-26.at.11.54.36.mov
Screen.Recording.2026-05-26.at.11.52.47.mov
Closes https://github.com/software-mansion/react-native-screens-labs/issues/1267
Changes
backgroundComponentprop with wrapper havingstyle={StyleSheet.absoluteFill}andpointerEvents="none"Before & after - visual documentation
ios18.mov
ios26.mov
Test plan
Checklist