feat(Android, FormSheet v5): Add support for fractional detents by t0maboro · Pull Request #4251 · software-mansion/react-native-screens

t0maboro · 2026-07-02T14:59:32Z

Description

Adds configurable detents to the new FormSheets on Android. Due to the native limitations, it allows passing 0-3 detents from JS, which are parsed to BottomSheetBehavior params (peek/half-expanded/expanded/max-height).
I am introducing a FormSheetBehaviorController which is a stateless mapper from a resolved detent config to BottomSheetBehavior, forcing a fresh layout pass so the behavior re-settles to the new detent configuration.

Additionally, I am making some bugfixes related to or exposed by introducing the sheet detents mechanism.

Enter-animation flicker on API < 30 - Material's BottomSheetBehavior registers a WindowInsetsAnimationCallback which updates translationY and is causing the sheet to jump during the enter animation (I am modifying translation on a custom slide-in animation). We clear that callback after the first layout, because we manage insets ourselves via a fixed container height, preventing the conflict.
Material only draws the BottomSheetDialog edge-to-edge when the theme opts in, and the nav bar is translucent; otherwise, the CoordinatorLayout (and our full-bleed dimming view) is inset below the status bar. We now force edge-to-edge on the dialog window on every API level.

Closes: https://github.com/software-mansion/react-native-screens-labs/issues/1551

Changes

Introduced FormSheetBehaviorController responsible for mapping the raw JS detents array into specific BottomSheetBehavior properties.
Disabled native insets animation to explicitly clear Material's WindowInsetsAnimationCallback, unblocking our custom translationY enter-animation.
Forced Edge-to-Edge in onAttachedToWindow() in FormSheetDialog on both the window decor and the internal Material containers (R.id.container, R.id.coordinator), ensuring the dimming view covers the status bar area and the FormSheetContainer space is predictable across different API levels.

Before & after - visual documentation

detents.mov

Test plan

Tested on the base example &

import React, { useState } from 'react';
import { Button, ScrollView, StyleSheet, Text, View } from 'react-native';
import { FormSheet, SafeAreaView } from 'react-native-screens/experimental';
import { scenarioDescription } from './scenario-description';
import { createScenario } from '@apps/tests/shared/helpers';
import { Colors } from '@apps/shared/styling';

const DETENT_CONFIGS = [
  { label: 'Single detent (0.5)', detents: [0.5] },
  { label: 'Full screen (1.0)', detents: [1.0] },
  { label: 'Two detents (0.3, 0.8)', detents: [0.3, 0.8] },
  { label: 'Half and full (0.5, 1.0)', detents: [0.5, 1.0] },
  { label: 'Three detents (0.2, 0.5, 0.9)', detents: [0.2, 0.5, 0.9] },
  { label: 'Three tall (0.35, 0.65, 1.0)', detents: [0.35, 0.65, 1.0] },
  { label: 'Default fallback (empty array)', detents: [] },
];

function SheetScenario({ label, detents }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <View style={styles.scenarioContainer}>
      <Button
        title={`Open: ${label}`}
        color={Colors.primary}
        onPress={() => setIsOpen(true)}
      />

      <FormSheet
        isOpen={isOpen}
        onNativeDismiss={() => setIsOpen(false)}
        detents={detents}>
        <View style={styles.sheetContent}>
          <Text style={styles.sheetTitle}>FormSheet Content</Text>
          <Text style={styles.sheetSubtitle}>
            Static configuration: {JSON.stringify(detents)}
          </Text>
          <View style={styles.spacing} />
          <Button
            title="Close sheet from JS"
            color={Colors.primary}
            onPress={() => setIsOpen(false)}
          />
        </View>
      </FormSheet>
    </View>
  );
}

function TestFormSheetBase() {
  return (
    <SafeAreaView edges={{top: true, bottom: true}} style={styles.container}>
      <Text style={styles.title}>FormSheet Configuration Tests</Text>

      <ScrollView
        style={styles.scrollContainer}
        contentContainerStyle={styles.scrollContent}>
        {DETENT_CONFIGS.map((config, index) => (
          <SheetScenario
            key={index}
            label={config.label}
            detents={config.detents}
          />
        ))}
      </ScrollView>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: Colors.offBackground,
  },
  scrollContainer: {
    flex: 1,
  },
  scrollContent: {
    padding: 16,
    paddingBottom: 40,
  },
  title: {
    fontSize: 20,
    fontWeight: 'bold',
    marginVertical: 20,
    color: Colors.text,
    textAlign: 'center',
  },
  scenarioContainer: {
    marginBottom: 16,
    backgroundColor: 'rgba(0,0,0,0.03)',
    padding: 12,
    borderRadius: 8,
    borderWidth: 1,
    borderColor: 'rgba(0,0,0,0.1)',
  },
  sheetContent: {
    flex: 1,
    backgroundColor: Colors.background,
    padding: 24,
    justifyContent: 'center',
    alignItems: 'center',
  },
  sheetTitle: {
    fontSize: 22,
    fontWeight: '600',
    marginBottom: 8,
    color: Colors.text,
  },
  sheetSubtitle: {
    fontSize: 14,
    color: Colors.text,
    opacity: 0.7,
    fontFamily: 'monospace',
  },
  spacing: {
    height: 32,
  },
});

export default createScenario(TestFormSheetBase, scenarioDescription);

Checklist

Included code example that can be used to test this change.
For visual changes, included screenshots / GIFs / recordings documenting the change.
For API changes, updated relevant public types.
Ensured that CI passes

Copilot

Pull request overview

Adds fractional detent support for the new Android FormSheet (gamma) by mapping a JS detents array into BottomSheetBehavior configuration, while also addressing visual/insets issues (enter-animation flicker on API < 30 and non-edge-to-edge dialog layout).

Changes:

Plumbs detents from the RN prop layer (FormSheetHostViewManager/FormSheetHost) into FormSheetConfig and FormSheetDialogManager.
Introduces FormSheetDetents + FormSheetBehaviorController to validate detent input and apply corresponding BottomSheetBehavior params (peek/half-expanded/expanded/maxHeight) with a forced re-layout.
Forces edge-to-edge rendering in FormSheetDialog and disables Material’s insets animation callback to prevent translationY conflicts with the custom enter animation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetHostViewManager.kt	Implements `detents` prop parsing from `ReadableArray` into a Kotlin list.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetHost.kt	Stores detents on the host and passes them into `FormSheetConfig`.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetDialogManager.kt	Resolves detents, triggers reconfiguration on open/config change, updates container height, and disables Material insets animation callback.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetDialog.kt	Forces edge-to-edge drawing for consistent dimming + layout across API levels.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetDetents.kt	Adds detent validation + helpers for computing pixel heights and container sizing.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetConfig.kt	Extends config with `detents`.
android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetBehaviorController.kt	Stateless mapper from resolved detents to `BottomSheetBehavior` properties.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

kkafar

Great job. I think that the abstractions you've introduced make sense.

I have series of remarks regarding some details. Let's iron them out before proceeding.

kkafar · 2026-07-03T09:00:59Z

+        isFitToContents = true
+        peekHeight = detents.firstHeight(sheetAvailableSpace)
+        maxHeight = detents.maxAllowedHeight(sheetAvailableSpace)
+        // TODO: @t0maboro - in v4 impl the state was passed as a param, consider the same approach


Yeah, it might be useful to support initialDetentIndex or whatever prop.

Not needed in this very moment though. Looks good. You might modify that on is-needed basis.

There was also some logic in v4 SheetDelegate impl. around the keyboard handling - I haven't verified whether it still applies in the new implementation, so leaving myself a note to revisit this line

kkafar · 2026-07-03T09:19:36Z

        hideNativeDimmingView(window)
        disableNativeWindowAnimation(window)


These lines have not beed modified in this PR, but I notice them here for the first time.

They are risky. AFAIK the window object you modify in their implementation is shared between FormSheetDialog view hierarchy, "original view hierarchy" (where react root view resides), and any other dialog opened before/after the form sheet.

Therefore modifying global window settings will affect behaviour of not only the formsheet, but also all other dialogs.

E.g. if you disable the dimming view this way, my prediction is that the <Modal /> component from react-native won't have dimming view anymore. Similarly the animations will be disabled.

Please verify this. In case I'm right (let's hope I'm wrong).

Okay! We did some research together with @t0maboro and it turns out that each Dialog on Android creates it's own window instance! That's great then.

https://cs.android.com/android/platform/superproject/+/android-16.0.0_r4:frameworks/base/core/java/android/app/Dialog.java;l=208-209 pasting here a link to the source code if we need to revisit it for some reason

kkafar · 2026-07-03T09:35:26Z

+    private fun forceEdgeToEdge() {
+        val window = window ?: return
+        WindowCompat.setDecorFitsSystemWindows(window, false)
+        findViewById<View>(com.google.android.material.R.id.container)?.fitsSystemWindows = false
+        findViewById<View>(com.google.android.material.R.id.coordinator)?.fitsSystemWindows = false
+    }


This is an important assumption. We MUST emphasise this in the component description that right now we enforce / assume edge-to-edge mode being enabled.

kkafar · 2026-07-03T10:10:14Z

@@ -81,12 +126,27 @@ class FormSheetDialogManager(
                override fun onPreDraw(): Boolean {
                    view.viewTreeObserver.removeOnPreDrawListener(this)
                    view.translationY = view.height.toFloat()


Why do we set the view.translationY here? You already do that in runEnterAnimation.

I've removed this line & it seems to be working just fine. Please see to it.

I've noticed this, because setting translationY for animation purposes in onPreDraw seems rather out of place.

kkafar · 2026-07-03T10:13:07Z

                override fun onPreDraw(): Boolean {
                    view.viewTreeObserver.removeOnPreDrawListener(this)
                    view.translationY = view.height.toFloat()
+                    disableMaterialInsetsAnimationCallback(view)


Also this one: why do we do it in onPreDraw? Can't we do it much earlier, e.g. after the BottomSheetBehavior of the formsheet is initialized for the very first time? When does BottomSheetBehavior / BottomSheetDialog register this callback?

it's registered on the first onLayoutChild call here: https://github.com/material-components/material-components-android/blob/release-1.13/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java#L556

I'm already changing it in the followup PR to use doOnLayout

react-native-screens/android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetDimensionsCoordinator.kt

Lines 46 to 50 in e3bd3db

private fun disableMaterialInsetsAnimationCallback(view: FrameLayout) {

view.doOnLayout {

ViewCompat.setWindowInsetsAnimationCallback(it, null)

}

}

- let me know if that's okay regarding timing, I did it on pre-draw here to ensure that I am after the layout pass

kkafar · 2026-07-03T10:15:16Z

+    private fun updateNativeContainerHeight() {
        val dialogDecorHeight = dialog.window?.decorView?.height ?: 0



Just a style guide -> if there is nothing to do if dialogDecorHeight == 0 then just early return and remove one level of indentation from the rest of the code.

kkafar · 2026-07-03T10:18:31Z

This would make more sense to take null as any other API in Android, instead of "empty callback".

kkafar · 2026-07-03T10:18:58Z

    }
+
+    companion object {
+        private const val LARGE_DETENT = 1.0


Suggested change

private const val LARGE_DETENT = 1.0

private const val LARGE_DETENT_FRACTION = 1.0

kkafar · 2026-07-03T10:21:14Z

+        // TODO: @t0maboro
+        // - a dedicated presentation manager should be introduced as on iOS,
+        // - invalidation flags logic should be implemented following other components convention
+        val isOpening = newConfig.isOpen && !formSheetConfig.isOpen


You already test for that earlier in this function. Please move this value to the top of the scope and reuse it.

t0maboro added 8 commits July 1, 2026 16:04

Prepare detents helper

5c15431

Bind detents from JS

d88dc66

Add support for fractional detents

b90d71a

Make behavior controller stateless

e003916

Minor cleanup

65ced3c

Disable insets material's insets handling

24b5cff

Enforce edge-to-edge for FormSheet on lower androids

0ad34ba

Proactively reconfigure sheet detents in subsequent presentations

0e6b6cd

t0maboro requested review from Copilot, kkafar, kligarski and kmichalikk July 2, 2026 14:59

Copilot started reviewing on behalf of t0maboro July 2, 2026 15:00 View session

Copilot AI reviewed Jul 2, 2026

View reviewed changes

t0maboro and others added 2 commits July 2, 2026 17:13

Apply suggestions from code review

6969349

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Cleanup

dc29e8b

kmichalikk approved these changes Jul 3, 2026

View reviewed changes

Comment thread android/src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetDetents.kt Outdated

Comment thread .../src/main/java/com/swmansion/rnscreens/gamma/modals/formsheet/FormSheetBehaviorController.kt

Rename & make private

1c1aa2e

kkafar reviewed Jul 3, 2026

View reviewed changes

t0maboro added 6 commits July 3, 2026 12:50

Add doc on the class level

269d207

Remove redundant line

d78d65a

reverse the condition

1d512b5

nullable dimmingview listener

c97048f

rename

5026fdd

Move isOpening/Closing to the top

63ca1dc

t0maboro requested a review from kkafar July 3, 2026 11:07

		hideNativeDimmingView(window)
		disableNativeWindowAnimation(window)

	private fun disableMaterialInsetsAnimationCallback(view: FrameLayout) {
	view.doOnLayout {
	ViewCompat.setWindowInsetsAnimationCallback(it, null)
	}
	}

		private fun updateNativeContainerHeight() {
		val dialogDecorHeight = dialog.window?.decorView?.height ?: 0

	private const val LARGE_DETENT = 1.0
	private const val LARGE_DETENT_FRACTION = 1.0

Uh oh!

Uh oh!

Conversation

t0maboro commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Before & after - visual documentation

Test plan

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

t0maboro commented Jul 2, 2026 •

edited

Loading