From d8c670eeb1a3942711923887de161a0a9caf5be1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 10:03:37 +0200
Subject: [PATCH 01/16] Define fitToContents for public API

---
 .../gamma/modals/form-sheet/FormSheet.tsx        |  6 ++++--
 .../gamma/modals/form-sheet/FormSheet.types.ts   |  3 ++-
 .../gamma/modals/form-sheet/FormSheetUtils.ts    | 16 ++++++++++++++++
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/src/components/gamma/modals/form-sheet/FormSheet.tsx b/src/components/gamma/modals/form-sheet/FormSheet.tsx
index 140f872507..24fe102c51 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.tsx
+++ b/src/components/gamma/modals/form-sheet/FormSheet.tsx
@@ -6,6 +6,7 @@ import {
   resolveInitialDetentIndex,
   resolveLargestUndimmedDetentIndex,
   resolveNativeCornerRadius,
+  resolveNativeDetents,
 } from './FormSheetUtils';
 
 export function FormSheet(props: FormSheetProps) {
@@ -18,8 +19,9 @@ export function FormSheet(props: FormSheetProps) {
   } = props;
 
   const nativeCornerRadius = resolveNativeCornerRadius(preferredCornerRadius);
+  const nativeDetents = resolveNativeDetents(detents);
 
-  const detentsCount = detents?.length ?? 0;
+  const detentsCount = nativeDetents?.length ?? 0;
 
   const resolvedInitialDetentIndex = resolveInitialDetentIndex(
     initialDetentIndex,
@@ -34,7 +36,7 @@ export function FormSheet(props: FormSheetProps) {
   return (
     <FormSheetHostNativeComponent
       style={styles.host}
-      detents={detents}
+      detents={nativeDetents}
       initialDetentIndex={resolvedInitialDetentIndex}
       largestUndimmedDetentIndex={resolvedUndimmedDetentIndex}
       preferredCornerRadius={nativeCornerRadius}
diff --git a/src/components/gamma/modals/form-sheet/FormSheet.types.ts b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
index 52db293cc8..0730af3465 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.types.ts
+++ b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
@@ -18,6 +18,7 @@ export interface FormSheetProps {
    */
   isOpen: boolean;
 
+  // TODO: @t0maboro - update description after implementing fitToContents
   /**
    * @summary An array of fractional screen heights (ranging from `0.0` to `1.0`) that define
    * the resting positions of the sheet.
@@ -27,7 +28,7 @@ export interface FormSheetProps {
    *
    * @platform ios
    */
-  detents?: number[] | undefined;
+  detents?: number[] | 'fitToContents' | undefined;
 
   /**
    * @summary Determines whether the sheet requests a grabber at the top.
diff --git a/src/components/gamma/modals/form-sheet/FormSheetUtils.ts b/src/components/gamma/modals/form-sheet/FormSheetUtils.ts
index d2b9fc55ed..33973712ec 100644
--- a/src/components/gamma/modals/form-sheet/FormSheetUtils.ts
+++ b/src/components/gamma/modals/form-sheet/FormSheetUtils.ts
@@ -1,11 +1,27 @@
 import type { FormSheetProps } from './FormSheet.types';
 
+// Predefined value for `fitToContents`. Keep in sync with native counterpart.
+export const NATIVE_FIT_TO_CONTENTS = -1.0;
 // Predefined values for `initialDetentIndex`. Keep in sync with native counterpart.
 const FORM_SHEET_LAST_DETENT = -1;
 // Predefined values for `largestUndimmedDetentIndex`. Keep in sync with native counterpart.
 const FORM_SHEET_ALWAYS_DIMMED = -1;
 const FORM_SHEET_NEVER_DIMMED = -2;
 
+export function resolveNativeDetents(
+  detents?: number[] | 'fitToContents',
+): number[] | undefined {
+  if (!detents) {
+    return undefined;
+  }
+
+  if (detents === 'fitToContents') {
+    return [NATIVE_FIT_TO_CONTENTS];
+  }
+
+  return detents;
+}
+
 export function resolveInitialDetentIndex(
   initialDetentIndex: FormSheetProps['initialDetentIndex'],
   detentsCount: number = 0,

From 5d0a71dfa5de8abfc077fc4a700575d4de8dd1fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 10:13:38 +0200
Subject: [PATCH 02/16] Prepare SFT

---
 .../single-feature-tests/form-sheet/index.ts  |  2 +
 .../index.tsx                                 | 68 +++++++++++++++++++
 .../scenario-description.ts                   | 10 +++
 .../scenario.md                               | 45 ++++++++++++
 4 files changed, 125 insertions(+)
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md

diff --git a/apps/src/tests/single-feature-tests/form-sheet/index.ts b/apps/src/tests/single-feature-tests/form-sheet/index.ts
index 35eff57f39..9f545bfbac 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/index.ts
+++ b/apps/src/tests/single-feature-tests/form-sheet/index.ts
@@ -1,6 +1,7 @@
 import type { ScenarioGroup } from '@apps/tests/shared/helpers';
 import TestFormSheetBase from './test-form-sheet-base-ios';
 import TestFormSheetExpandScrollView from './test-form-sheet-expand-scroll-view-ios';
+import TestFormSheetFitToContents from './test-form-sheet-fit-to-contents-ios';
 import TestFormSheetGrabberVisible from './test-form-sheet-grabber-visible-ios';
 import TestFormSheetInitialDetentIndex from './test-form-sheet-initial-detent-index-ios';
 import TestFormSheetLargestUndimmedDetentIndex from './test-form-sheet-largest-undimmed-detent-index-ios';
@@ -11,6 +12,7 @@ import TestFormSheetPresentationState from './test-form-sheet-presentation-state
 const scenarios = {
   TestFormSheetBase,
   TestFormSheetExpandScrollView,
+  TestFormSheetFitToContents,
   TestFormSheetGrabberVisible,
   TestFormSheetInitialDetentIndex,
   TestFormSheetLargestUndimmedDetentIndex,
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
new file mode 100644
index 0000000000..9ab36c3392
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
@@ -0,0 +1,68 @@
+import React, { useState } from 'react';
+import { Button, StyleSheet, Text, View } from 'react-native';
+import { FormSheet } from 'react-native-screens/experimental';
+import { scenarioDescription } from './scenario-description';
+import { createScenario } from '@apps/tests/shared/helpers';
+import { Colors } from '@apps/shared/styling';
+
+export function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>FormSheet Test</Text>
+      <Button
+        title="Open FormSheet"
+        color={Colors.primary}
+        onPress={() => setIsOpen(true)}
+      />
+      <FormSheet
+        isOpen={isOpen}
+        onNativeDismiss={() => setIsOpen(false)}
+        detents="fitToContents">
+        <View style={styles.sheetContent}>
+          <Text style={styles.sheetTitle}>FormSheet content</Text>
+          <View style={styles.spacing} />
+          <Button
+            title="Dismiss from JS"
+            color={Colors.primary}
+            onPress={() => setIsOpen(false)}
+          />
+        </View>
+      </FormSheet>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: Colors.offBackground,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    marginBottom: 20,
+    color: Colors.text,
+  },
+  sheetContent: {
+    flex: 1,
+    backgroundColor: Colors.background,
+    padding: 24,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  sheetTitle: {
+    fontSize: 22,
+    fontWeight: '600',
+    marginBottom: 12,
+    color: Colors.text,
+  },
+  spacing: {
+    height: 32,
+  },
+});
+
+export default createScenario(App, scenarioDescription);
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
new file mode 100644
index 0000000000..032c6ef444
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
@@ -0,0 +1,10 @@
+import type { ScenarioDescription } from '@apps/tests/shared/helpers';
+
+export const scenarioDescription: ScenarioDescription = {
+  name: 'FitToContents',
+  key: 'test-form-sheet-fit-to-contents-ios',
+  details: 'Allows to test fitToContents detents setup of FormSheet component.',
+  platforms: ['ios'],
+  e2eCoverage: 'tbd',
+  smokeTest: false,
+};
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md
new file mode 100644
index 0000000000..12ed06ce61
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md
@@ -0,0 +1,45 @@
+# Test Scenario: Test case name
+
+Example: Test Scenario: colorScheme
+
+## Details
+
+**Description:** Provide a high-level overview of the feature or property being tested. Identify the specific functionality and transitions being validated, while defining the success criteria. Focus on the underlying goal, such as preventing specific UI regressions, visual glitches, or inconsistent behaviors.
+
+**OS test creation version:** Specify the OS version used during the initial implementation of the scenario and screen. This serves as a baseline where the described behavior and visual results were confirmed to work correctly.
+
+## E2E test
+
+Yes/No/Other
+
+- If **Yes:** Add a description of what is covered by automated E2E tests and what remains manual only.
+- If **No:** - If the scenario cannot be automated, include an explanation why.
+- If **Other:** Add relevant information e.g. research is required, or automation is possible and planned but not yet implemented.
+
+## Prerequisites
+
+List of devices or platforms required to run this test.
+
+Example: iOS physical device, Android emulator
+
+## Note (Optional)
+
+Include any critical information for scenario execution not covered elsewhere. Use this section to document Known Issues (KI) or specific behaviors that might appear misleading but are considered expected results. Define rules that apply to the entire scenario to avoid repetition in individual steps.
+
+## Steps
+
+Step-by-step instructions for a tester to manually verify the scenario.
+
+You can use subheadings to group steps logically (e.g., ### Baseline) or define separate step sections for different device types if their execution paths differ significantly.
+
+1. Navigate to ...
+
+- [ ] Expected:
+
+2. Tap ...
+
+- [ ] Expected:
+
+3. Verify that ...
+
+- [ ] Expected:

From 1acf99e8b18db51c88e65b0ce25e80f6015a356e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 10:38:07 +0200
Subject: [PATCH 03/16] Prepare ContentWrapper native component

---
 .../RNSFormSheetContentWrapperComponentView.h | 14 +++++++
 ...RNSFormSheetContentWrapperComponentView.mm | 39 +++++++++++++++++++
 .../RNSFormSheetContentWrapperDelegate.h      | 13 +++++++
 ios/stubs/RNSGammaStubs.h                     |  3 ++
 ios/stubs/RNSGammaStubs.mm                    |  3 ++
 package.json                                  |  3 ++
 .../gamma/modals/form-sheet/FormSheet.tsx     |  9 ++++-
 .../FormSheetContentWrapperNativeComponent.ts | 13 +++++++
 8 files changed, 95 insertions(+), 2 deletions(-)
 create mode 100644 ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
 create mode 100644 ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
 create mode 100644 ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
 create mode 100644 src/fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent.ts

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
new file mode 100644
index 0000000000..88447defe8
--- /dev/null
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#import "RNSFormSheetContentWrapperDelegate.h"
+#import "RNSReactBaseView.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNSFormSheetContentWrapperComponentView : RNSReactBaseView
+
+@property (nonatomic, weak, nullable) id<RNSFormSheetContentWrapperDelegate> delegate;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
new file mode 100644
index 0000000000..dd247af4ba
--- /dev/null
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
@@ -0,0 +1,39 @@
+#import "RNSFormSheetContentWrapperComponentView.h"
+
+#import <react/renderer/components/rnscreens/ComponentDescriptors.h>
+#import <react/renderer/components/rnscreens/Props.h>
+#import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
+
+namespace react = facebook::react;
+
+@interface RNSFormSheetContentWrapperComponentView () <RCTRNSFormSheetContentWrapperViewProtocol>
+@end
+
+#pragma mark - RCTComponentViewProtocol
+
+@implementation RNSFormSheetContentWrapperComponentView
+
++ (react::ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return react::concreteComponentDescriptorProvider<react::RNSFormSheetContentWrapperComponentDescriptor>();
+}
+
+- (void)updateLayoutMetrics:(const react::LayoutMetrics &)layoutMetrics
+           oldLayoutMetrics:(const react::LayoutMetrics &)oldLayoutMetrics
+{
+  [super updateLayoutMetrics:layoutMetrics oldLayoutMetrics:oldLayoutMetrics];
+
+  CGFloat newHeight = layoutMetrics.frame.size.height;
+  CGFloat oldHeight = oldLayoutMetrics.frame.size.height;
+
+  if (newHeight != oldHeight) {
+    [self.delegate contentWrapper:self didChangeContentHeight:newHeight];
+  }
+}
+
+@end
+
+Class<RCTComponentViewProtocol> RNSFormSheetContentWrapperCls(void)
+{
+  return RNSFormSheetContentWrapperComponentView.class;
+}
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
new file mode 100644
index 0000000000..5d0bd7cbc4
--- /dev/null
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
@@ -0,0 +1,13 @@
+#pragma once
+
+@class RNSFormSheetContentWrapperComponentView;
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSFormSheetContentWrapperDelegate <NSObject>
+
+- (void)contentWrapper:(RNSFormSheetContentWrapperComponentView *)wrapper didChangeContentHeight:(CGFloat)contentHeight;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/stubs/RNSGammaStubs.h b/ios/stubs/RNSGammaStubs.h
index dbd82637db..7b496f2f13 100644
--- a/ios/stubs/RNSGammaStubs.h
+++ b/ios/stubs/RNSGammaStubs.h
@@ -27,4 +27,7 @@ NS_ASSUME_NONNULL_BEGIN
 @interface RNSFormSheetHostComponentView : NSObject
 @end
 
+@interface RNSFormSheetContentWrapperComponentView : NSObject
+@end
+
 NS_ASSUME_NONNULL_END
diff --git a/ios/stubs/RNSGammaStubs.mm b/ios/stubs/RNSGammaStubs.mm
index e0f6433df7..904a813f6a 100644
--- a/ios/stubs/RNSGammaStubs.mm
+++ b/ios/stubs/RNSGammaStubs.mm
@@ -17,3 +17,6 @@ @implementation RNSScrollViewMarkerComponentView
 
 @implementation RNSFormSheetHostComponentView
 @end
+
+@implementation RNSFormSheetContentWrapperComponentView
+@end
diff --git a/package.json b/package.json
index f23c5a4220..d4e366e226 100644
--- a/package.json
+++ b/package.json
@@ -223,6 +223,9 @@
         },
         "RNSFormSheetHost": {
           "className": "RNSFormSheetHostComponentView"
+        },
+        "RNSFormSheetContentWrapper": {
+          "className": "RNSFormSheetContentWrapperComponentView"
         }
       }
     }
diff --git a/src/components/gamma/modals/form-sheet/FormSheet.tsx b/src/components/gamma/modals/form-sheet/FormSheet.tsx
index 24fe102c51..adf05e9929 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.tsx
+++ b/src/components/gamma/modals/form-sheet/FormSheet.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import { StyleSheet } from 'react-native';
 import FormSheetHostNativeComponent from '../../../../fabric/gamma/modals/form-sheet/FormSheetHostNativeComponent';
+import FormSheetContentWrapperNativeComponent from '../../../../fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent';
 import type { FormSheetProps } from './FormSheet.types';
 import {
   resolveInitialDetentIndex,
@@ -11,6 +12,7 @@ import {
 
 export function FormSheet(props: FormSheetProps) {
   const {
+    children,
     detents,
     initialDetentIndex,
     largestUndimmedDetentIndex,
@@ -40,8 +42,11 @@ export function FormSheet(props: FormSheetProps) {
       initialDetentIndex={resolvedInitialDetentIndex}
       largestUndimmedDetentIndex={resolvedUndimmedDetentIndex}
       preferredCornerRadius={nativeCornerRadius}
-      {...rest}
-    />
+      {...rest}>
+      <FormSheetContentWrapperNativeComponent>
+        {children}
+      </FormSheetContentWrapperNativeComponent>
+    </FormSheetHostNativeComponent>
   );
 }
 
diff --git a/src/fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent.ts b/src/fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent.ts
new file mode 100644
index 0000000000..889a95c132
--- /dev/null
+++ b/src/fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent.ts
@@ -0,0 +1,13 @@
+'use client';
+
+import type { ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+
+interface NativeProps extends ViewProps {}
+
+export default codegenNativeComponent<NativeProps>(
+  'RNSFormSheetContentWrapper',
+  {
+    excludedPlatforms: ['android'],
+  },
+);

From 74903baf508cd40002bf4250e3804b7a84140f79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:21:00 +0200
Subject: [PATCH 04/16] Add support for fitToContents

---
 .../RNSFormSheetConfigurationApplicator.mm    |  2 +-
 .../form-sheet/RNSFormSheetContentView.h      |  3 ++
 ...RNSFormSheetContentWrapperComponentView.mm | 38 ++++++++++++++--
 .../form-sheet/RNSFormSheetDetentResolver.h   |  7 ++-
 .../form-sheet/RNSFormSheetDetentResolver.mm  | 43 ++++++++++++++-----
 .../RNSFormSheetHostComponentView.mm          | 24 +++++++++++
 .../modals/form-sheet/RNSFormSheetProviders.h |  1 +
 7 files changed, 102 insertions(+), 16 deletions(-)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetConfigurationApplicator.mm b/ios/gamma/modals/form-sheet/RNSFormSheetConfigurationApplicator.mm
index 68059d4cb9..f659017553 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetConfigurationApplicator.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetConfigurationApplicator.mm
@@ -54,7 +54,7 @@ - (void)applyConfigurationWithAppearanceProvider:(id<RNSFormSheetAppearanceProvi
   // Behavior data
 
   NSArray<UISheetPresentationControllerDetent *> *nativeDetents =
-      [RNSFormSheetDetentResolver buildSheetDetentsForFractions:behaviorProvider.detents];
+      [RNSFormSheetDetentResolver buildSheetDetentsWithBehaviorProvider:behaviorProvider];
 
   UISheetPresentationControllerDetentIdentifier initialDetentIdentifier = nil;
   if (!_initialDetentApplied) {
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentView.h b/ios/gamma/modals/form-sheet/RNSFormSheetContentView.h
index 15fa1336d9..1a14a3a3da 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentView.h
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentView.h
@@ -1,11 +1,14 @@
 #pragma once
 
 #import <UIKit/UIKit.h>
+#import "RNSFormSheetContentWrapperDelegate.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 @interface RNSFormSheetContentView : UIView
 
+@property (nonatomic, weak, nullable) id<RNSFormSheetContentWrapperDelegate> contentWrapperDelegate;
+
 - (void)insertReactSubview:(UIView *)subview atIndex:(NSInteger)index;
 - (void)removeReactSubview:(UIView *)subview;
 
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
index dd247af4ba..8c8dfc7b26 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
@@ -1,18 +1,45 @@
 #import "RNSFormSheetContentWrapperComponentView.h"
 
+#import <React/RCTMountingTransactionObserving.h>
 #import <react/renderer/components/rnscreens/ComponentDescriptors.h>
 #import <react/renderer/components/rnscreens/Props.h>
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
 
+#import "RNSFormSheetContentView.h"
+
 namespace react = facebook::react;
 
-@interface RNSFormSheetContentWrapperComponentView () <RCTRNSFormSheetContentWrapperViewProtocol>
+@interface RNSFormSheetContentWrapperComponentView () <RCTRNSFormSheetContentWrapperViewProtocol,
+                                                       RCTMountingTransactionObserving>
 @end
 
-#pragma mark - RCTComponentViewProtocol
-
 @implementation RNSFormSheetContentWrapperComponentView
 
+- (id<RNSFormSheetContentWrapperDelegate>)resolveFormSheetContentWrapperDelegate
+{
+  UIView *view = self.superview;
+  while (view != nil) {
+    if ([view isKindOfClass:[RNSFormSheetContentView class]]) {
+      return ((RNSFormSheetContentView *)view).contentWrapperDelegate;
+    }
+    view = view.superview;
+  }
+  return nil;
+}
+
+#pragma mark - RCTMountingTransactionObserving
+
+- (void)mountingTransactionDidMount:(const facebook::react::MountingTransaction &)transaction
+               withSurfaceTelemetry:(const facebook::react::SurfaceTelemetry &)surfaceTelemetry
+{
+  id<RNSFormSheetContentWrapperDelegate> delegate = [self resolveFormSheetContentWrapperDelegate];
+  if (delegate && self.frame.size.height > 0) {
+    [delegate contentWrapper:self didChangeContentHeight:self.frame.size.height];
+  }
+}
+
+#pragma mark - RCTComponentViewProtocol
+
 + (react::ComponentDescriptorProvider)componentDescriptorProvider
 {
   return react::concreteComponentDescriptorProvider<react::RNSFormSheetContentWrapperComponentDescriptor>();
@@ -27,7 +54,10 @@ - (void)updateLayoutMetrics:(const react::LayoutMetrics &)layoutMetrics
   CGFloat oldHeight = oldLayoutMetrics.frame.size.height;
 
   if (newHeight != oldHeight) {
-    [self.delegate contentWrapper:self didChangeContentHeight:newHeight];
+    id<RNSFormSheetContentWrapperDelegate> delegate = [self resolveFormSheetContentWrapperDelegate];
+    if (delegate) {
+      [delegate contentWrapper:self didChangeContentHeight:newHeight];
+    }
   }
 }
 
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.h b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.h
index 09358252ad..7624b3d887 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.h
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.h
@@ -6,8 +6,12 @@
 #import <vector>
 #endif
 
+@protocol RNSFormSheetBehaviorProvider;
+
 NS_ASSUME_NONNULL_BEGIN
 
+// Predefined value for `fitToContents` detent.
+static const double kRNSFormSheetFitToContents = -1.0;
 // Predefined values for `initialDetentIndex`.
 static NSInteger const kRNSFormSheetLastDetent = -1;
 // Predefined values for `largestUndimmedDetentIndex`.
@@ -18,7 +22,8 @@ static NSInteger const kRNSFormSheetNeverDimmed = -2;
 
 #if !TARGET_OS_TV && defined(__cplusplus)
 
-+ (NSArray<UISheetPresentationControllerDetent *> *)buildSheetDetentsForFractions:(const std::vector<double> &)detents;
++ (NSArray<UISheetPresentationControllerDetent *> *)buildSheetDetentsWithBehaviorProvider:
+    (id<RNSFormSheetBehaviorProvider>)provider;
 
 #endif // !TARGET_OS_TV && __cplusplus
 
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
index 52da6cf8a0..1856b64191 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
@@ -1,5 +1,6 @@
 #import "RNSFormSheetDetentResolver.h"
 #import "RNSDefines.h"
+#import "RNSFormSheetProviders.h"
 
 #import <React/RCTLog.h>
 
@@ -8,6 +9,9 @@
 static BOOL RNSAreDetentsValid(const std::vector<double> &detents)
 {
   for (double currentDetent : detents) {
+    if (currentDetent == kRNSFormSheetFitToContents) {
+      continue;
+    }
     if (isnan(currentDetent)) {
       return NO;
     }
@@ -30,8 +34,10 @@ static BOOL RNSAreDetentsStrictlyAscending(const std::vector<double> &detents)
 
 @implementation RNSFormSheetDetentResolver
 
-+ (NSArray<UISheetPresentationControllerDetent *> *)buildSheetDetentsForFractions:(const std::vector<double> &)detents
++ (NSArray<UISheetPresentationControllerDetent *> *)buildSheetDetentsWithBehaviorProvider:
+    (id<RNSFormSheetBehaviorProvider>)provider
 {
+  const std::vector<double> &detents = provider.detents;
   size_t detentsCount = detents.size();
 
   // Defaults to large detent across all iOS versions
@@ -56,17 +62,30 @@ @implementation RNSFormSheetDetentResolver
 
 #if RNS_IPHONE_OS_VERSION_AVAILABLE(16_0)
   if (@available(iOS 16.0, *)) {
+    __weak id<RNSFormSheetBehaviorProvider> weakProvider = provider;
+
     for (size_t i = 0; i < detentsCount; i++) {
       double fraction = detents[i];
       NSString *ident = [NSString stringWithFormat:@"%zu", i];
-
-      [nativeDetents
-          addObject:[UISheetPresentationControllerDetent
-                        customDetentWithIdentifier:ident
-                                          resolver:^CGFloat(
-                                              id<UISheetPresentationControllerDetentResolutionContext> context) {
-                                            return context.maximumDetentValue * fraction;
-                                          }]];
+      if (fraction == kRNSFormSheetFitToContents) {
+        [nativeDetents
+            addObject:[UISheetPresentationControllerDetent
+                          customDetentWithIdentifier:ident
+                                            resolver:^CGFloat(
+                                                id<UISheetPresentationControllerDetentResolutionContext> context) {
+                                              CGFloat currentHeight =
+                                                  weakProvider ? [weakProvider contentHeight] : -1.0;
+                                              return currentHeight;
+                                            }]];
+      } else {
+        [nativeDetents
+            addObject:[UISheetPresentationControllerDetent
+                          customDetentWithIdentifier:ident
+                                            resolver:^CGFloat(
+                                                id<UISheetPresentationControllerDetentResolutionContext> context) {
+                                              return context.maximumDetentValue * fraction;
+                                            }]];
+      }
     }
   } else
 #endif // RNS_IPHONE_OS_VERSION_AVAILABLE(16_0)
@@ -74,7 +93,11 @@ @implementation RNSFormSheetDetentResolver
     // iOS 15 Legacy Fallback
     if (detentsCount == 1) {
       double firstDetentFraction = detents[0];
-      if (firstDetentFraction < 1.0) {
+      if (firstDetentFraction == kRNSFormSheetFitToContents) {
+        RCTLogError(
+            @"[RNScreens] 'fitToContents' is unsupported on iOS versions below 16. Falling back to medium detent.");
+        [nativeDetents addObject:UISheetPresentationControllerDetent.mediumDetent];
+      } else if (firstDetentFraction < 1.0) {
         [nativeDetents addObject:UISheetPresentationControllerDetent.mediumDetent];
       } else {
         [nativeDetents addObject:UISheetPresentationControllerDetent.largeDetent];
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetHostComponentView.mm b/ios/gamma/modals/form-sheet/RNSFormSheetHostComponentView.mm
index affa11e822..1a189a73d9 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetHostComponentView.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetHostComponentView.mm
@@ -1,6 +1,8 @@
 #import "RNSFormSheetHostComponentView.h"
 #import "RNSFormSheetContentController.h"
 #import "RNSFormSheetContentView.h"
+#import "RNSFormSheetContentWrapperComponentView.h"
+#import "RNSFormSheetContentWrapperDelegate.h"
 #import "RNSFormSheetDetentResolver.h"
 #import "RNSFormSheetHostEventEmitter.h"
 #import "RNSFormSheetHostShadowStateProxy.h"
@@ -16,6 +18,7 @@
 
 @interface RNSFormSheetHostComponentView () <RCTMountingTransactionObserving,
                                              RNSFormSheetContentControllerDelegate,
+                                             RNSFormSheetContentWrapperDelegate,
                                              RNSFormSheetPresentationProvider,
                                              RNSFormSheetAppearanceProvider,
                                              RNSFormSheetBehaviorProvider>
@@ -36,6 +39,8 @@ @implementation RNSFormSheetHostComponentView {
   NSInteger _largestUndimmedDetentIndex;
   NSInteger _initialDetentIndex;
   BOOL _prefersScrollingExpandsWhenScrolledToEdge;
+
+  CGFloat _contentHeight;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -67,6 +72,8 @@ - (void)resetProps
   _largestUndimmedDetentIndex = kRNSFormSheetAlwaysDimmed;
   _initialDetentIndex = 0;
   _prefersScrollingExpandsWhenScrolledToEdge = YES;
+
+  _contentHeight = 0.0;
 }
 
 - (void)setupController
@@ -77,6 +84,8 @@ - (void)setupController
   _controller.presentationProvider = self;
   _controller.appearanceProvider = self;
   _controller.behaviorProvider = self;
+
+  _controller.contentView.contentWrapperDelegate = self;
 }
 
 - (void)didMoveToWindow
@@ -103,6 +112,21 @@ - (nullable UIWindow *)hostWindow
   return _detents;
 }
 
+- (CGFloat)contentHeight
+{
+  return _contentHeight;
+}
+
+#pragma mark - RNSFormSheetContentWrapperDelegate
+
+- (void)contentWrapper:(RNSFormSheetContentWrapperComponentView *)wrapper didChangeContentHeight:(CGFloat)contentHeight
+{
+  if (_contentHeight != contentHeight) {
+    _contentHeight = contentHeight;
+    [_controller setNeedsBehaviorUpdate];
+  }
+}
+
 #pragma mark - RNSFormSheetContentControllerDelegate
 
 - (void)sheetControllerDidNativeDismiss:(RNSFormSheetContentController *)controller
diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetProviders.h b/ios/gamma/modals/form-sheet/RNSFormSheetProviders.h
index f005af4b90..3eb3c321e4 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetProviders.h
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetProviders.h
@@ -30,6 +30,7 @@ NS_ASSUME_NONNULL_BEGIN
 #endif
 - (NSInteger)initialDetentIndex;
 - (BOOL)prefersScrollingExpandsWhenScrolledToEdge;
+- (CGFloat)contentHeight;
 
 @end
 

From 10551df19a9351c854e1f0f3fb47819add85263a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:21:48 +0200
Subject: [PATCH 05/16] Fix JS styles for fitToContents

---
 .../gamma/modals/form-sheet/FormSheet.tsx         | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/components/gamma/modals/form-sheet/FormSheet.tsx b/src/components/gamma/modals/form-sheet/FormSheet.tsx
index adf05e9929..7ffaff1b3e 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.tsx
+++ b/src/components/gamma/modals/form-sheet/FormSheet.tsx
@@ -35,6 +35,8 @@ export function FormSheet(props: FormSheetProps) {
     detentsCount,
   );
 
+  const isFitToContents = detents === 'fitToContents';
+
   return (
     <FormSheetHostNativeComponent
       style={styles.host}
@@ -43,7 +45,12 @@ export function FormSheet(props: FormSheetProps) {
       largestUndimmedDetentIndex={resolvedUndimmedDetentIndex}
       preferredCornerRadius={nativeCornerRadius}
       {...rest}>
-      <FormSheetContentWrapperNativeComponent>
+      <FormSheetContentWrapperNativeComponent
+        style={
+          isFitToContents
+            ? styles.absoluteWithNoBottom
+            : StyleSheet.absoluteFill
+        }>
         {children}
       </FormSheetContentWrapperNativeComponent>
     </FormSheetHostNativeComponent>
@@ -62,4 +69,10 @@ const styles = StyleSheet.create({
     top: 0,
     left: 0,
   },
+  absoluteWithNoBottom: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
 });

From 3669b988a412adf6b7630eaa8b9d186dc458adbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:23:26 +0200
Subject: [PATCH 06/16] Update example

---
 .../index.tsx                                 | 55 +++++++++++++++++--
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
index 9ab36c3392..281ec482f4 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
@@ -7,6 +7,12 @@ import { Colors } from '@apps/shared/styling';
 
 export function App() {
   const [isOpen, setIsOpen] = useState(false);
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  const handleDismiss = () => {
+    setIsOpen(false);
+    setTimeout(() => setIsExpanded(false), 300);
+  };
 
   return (
     <View style={styles.container}>
@@ -18,15 +24,39 @@ export function App() {
       />
       <FormSheet
         isOpen={isOpen}
-        onNativeDismiss={() => setIsOpen(false)}
+        onNativeDismiss={handleDismiss}
         detents="fitToContents">
         <View style={styles.sheetContent}>
           <Text style={styles.sheetTitle}>FormSheet content</Text>
+
+          <Text style={styles.description}>
+            This sheet dynamically wraps its content. Press the button below to
+            change the height.
+          </Text>
+
+          <View style={styles.spacing} />
+
+          <Button
+            title={isExpanded ? 'Collapse Content' : 'Expand Content'}
+            color={Colors.primary}
+            onPress={() => setIsExpanded(!isExpanded)}
+          />
+
+          {isExpanded && (
+            <View style={styles.extraContentBox}>
+              <Text style={styles.extraText}>
+                Here is some extra content! The FormSheet should seamlessly
+                animate to accommodate this new height without any glitches.
+              </Text>
+            </View>
+          )}
+
           <View style={styles.spacing} />
+
           <Button
             title="Dismiss from JS"
             color={Colors.primary}
-            onPress={() => setIsOpen(false)}
+            onPress={handleDismiss}
           />
         </View>
       </FormSheet>
@@ -48,7 +78,6 @@ const styles = StyleSheet.create({
     color: Colors.text,
   },
   sheetContent: {
-    flex: 1,
     backgroundColor: Colors.background,
     padding: 24,
     justifyContent: 'center',
@@ -60,8 +89,26 @@ const styles = StyleSheet.create({
     marginBottom: 12,
     color: Colors.text,
   },
+  description: {
+    fontSize: 16,
+    textAlign: 'center',
+    color: Colors.text,
+    paddingHorizontal: 16,
+  },
+  extraContentBox: {
+    marginTop: 20,
+    padding: 16,
+    backgroundColor: Colors.offBackground,
+    borderRadius: 8,
+    width: '100%',
+  },
+  extraText: {
+    fontSize: 15,
+    color: Colors.text,
+    textAlign: 'center',
+  },
   spacing: {
-    height: 32,
+    height: 24,
   },
 });
 

From c2fe0c0f2a7ec5551ad6abd774e450bf3b9d5c62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:28:44 +0200
Subject: [PATCH 07/16] Add scenario description

---
 .../scenario-description.ts                   |  4 +-
 .../scenario.md                               | 61 ++++++++++++-------
 2 files changed, 40 insertions(+), 25 deletions(-)

diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
index 032c6ef444..c21a9fc2a7 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario-description.ts
@@ -1,9 +1,9 @@
 import type { ScenarioDescription } from '@apps/tests/shared/helpers';
 
 export const scenarioDescription: ScenarioDescription = {
-  name: 'FitToContents',
+  name: 'Fit to contents',
   key: 'test-form-sheet-fit-to-contents-ios',
-  details: 'Allows to test fitToContents detents setup of FormSheet component.',
+  details: 'Allows to test the fitToContents detent and dynamic height changes of the FormSheet component.',
   platforms: ['ios'],
   e2eCoverage: 'tbd',
   smokeTest: false,
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md
index 12ed06ce61..4d5e4de7fe 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/scenario.md
@@ -1,45 +1,60 @@
-# Test Scenario: Test case name
-
-Example: Test Scenario: colorScheme
+# Test Scenario: Fit to contents
 
 ## Details
 
-**Description:** Provide a high-level overview of the feature or property being tested. Identify the specific functionality and transitions being validated, while defining the success criteria. Focus on the underlying goal, such as preventing specific UI regressions, visual glitches, or inconsistent behaviors.
+**Description:** Verify the `fitToContents` for the `FormSheet` component. This test ensures that the FormSheet calculates its initial height to wrap its content upon opening, and dynamically animates to a new height when the internal content size changes.
 
-**OS test creation version:** Specify the OS version used during the initial implementation of the scenario and screen. This serves as a baseline where the described behavior and visual results were confirmed to work correctly.
+**OS test creation version:** iOS: 18.6 and 26.4, iPadOS 26.4
 
 ## E2E test
 
-Yes/No/Other
-
-- If **Yes:** Add a description of what is covered by automated E2E tests and what remains manual only.
-- If **No:** - If the scenario cannot be automated, include an explanation why.
-- If **Other:** Add relevant information e.g. research is required, or automation is possible and planned but not yet implemented.
+Other: Planned, but will be implemented separately.
 
 ## Prerequisites
 
-List of devices or platforms required to run this test.
+- iOS device or simulator: iPhone and iPad
+- On iPad: Ensure the device is in full-screen mode, regular width, regular height size class
 
-Example: iOS physical device, Android emulator
+## Note
 
-## Note (Optional)
-
-Include any critical information for scenario execution not covered elsewhere. Use this section to document Known Issues (KI) or specific behaviors that might appear misleading but are considered expected results. Define rules that apply to the entire scenario to avoid repetition in individual steps.
+- On iPad: The FormSheet is presented as a **centered floating panel**. The `fitToContents` behavior still applies to the height of this panel seamlessly, while its width remains fixed. Therefore, explicit separate steps for iPad are omitted.
 
 ## Steps
 
-Step-by-step instructions for a tester to manually verify the scenario.
+### Baseline
+
+1. Launch the app and navigate to the **Fit to contents** screen.
+
+- [ ] Expected: Content with the button "Open FormSheet" is shown.
+
+---
+
+### Initialization & `fitToContents` Verification
+
+2. Tap the "Open FormSheet" button.
+
+- [ ] Expected: The FormSheet opens smoothly. Its height is matched to its internal content (it will have an extra empty space on the bottom which is originating from native inset application). There are no visual jumps during the initial presentation animation.
+
+---
+
+### Dynamic Height Adaptation
+
+3. Tap the "Expand Content" button inside the FormSheet.
+
+- [ ] Expected: The extra text box appears. The native FormSheet smoothly animates and grows in height to fully accommodate the newly added content without any visual glitches.
+
+---
 
-You can use subheadings to group steps logically (e.g., ### Baseline) or define separate step sections for different device types if their execution paths differ significantly.
+### Dynamic Height Adaptation
 
-1. Navigate to ...
+4. Tap the "Collapse Content" button.
 
-- [ ] Expected:
+- [ ] Expected: The extra text box disappears. The native FormSheet smoothly animates and shrinks back to its original, smaller height.
 
-2. Tap ...
+---
 
-- [ ] Expected:
+### Dismissal Verification
 
-3. Verify that ...
+5. Tap the "Dismiss from JS" button (or swipe down completely).
 
-- [ ] Expected:
+- [ ] Expected: The FormSheet dismisses smoothly and returns the user to the underlying main screen.

From e4a34e42cfc5bc072c719e6c4ba93d746e816df5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:38:13 +0200
Subject: [PATCH 08/16] Fix frame only for the 1st transaction

---
 ...RNSFormSheetContentWrapperComponentView.mm | 23 ++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
index 8c8dfc7b26..658fafc439 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
@@ -13,7 +13,22 @@ @interface RNSFormSheetContentWrapperComponentView () <RCTRNSFormSheetContentWra
                                                        RCTMountingTransactionObserving>
 @end
 
-@implementation RNSFormSheetContentWrapperComponentView
+@implementation RNSFormSheetContentWrapperComponentView {
+  BOOL _initialHeightReported;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    [self initState];
+  }
+  return self;
+}
+
+- (void)initState
+{
+  _initialHeightReported = NO;
+}
 
 - (id<RNSFormSheetContentWrapperDelegate>)resolveFormSheetContentWrapperDelegate
 {
@@ -32,6 +47,12 @@ @implementation RNSFormSheetContentWrapperComponentView
 - (void)mountingTransactionDidMount:(const facebook::react::MountingTransaction &)transaction
                withSurfaceTelemetry:(const facebook::react::SurfaceTelemetry &)surfaceTelemetry
 {
+  // We only need to catch the initial mount because subsequent dynamic height changes
+  // are handled directly by `updateLayoutMetrics`.
+  if (_initialHeightReported) {
+    return;
+  }
+
   id<RNSFormSheetContentWrapperDelegate> delegate = [self resolveFormSheetContentWrapperDelegate];
   if (delegate && self.frame.size.height > 0) {
     [delegate contentWrapper:self didChangeContentHeight:self.frame.size.height];

From 6110362bd0739777e6dc82594941e97fbab1635d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:38:35 +0200
Subject: [PATCH 09/16] Remove confusing timeout

---
 .../form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx     | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
index 281ec482f4..252e46096b 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-fit-to-contents-ios/index.tsx
@@ -11,7 +11,6 @@ export function App() {
 
   const handleDismiss = () => {
     setIsOpen(false);
-    setTimeout(() => setIsExpanded(false), 300);
   };
 
   return (

From 2c73bb9a7681d50d7c9b4283ba3a5b23f851f0ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 13:41:31 +0200
Subject: [PATCH 10/16] Fix

---
 .../modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
index 658fafc439..6cc8d1d0ea 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.mm
@@ -55,6 +55,7 @@ - (void)mountingTransactionDidMount:(const facebook::react::MountingTransaction
 
   id<RNSFormSheetContentWrapperDelegate> delegate = [self resolveFormSheetContentWrapperDelegate];
   if (delegate && self.frame.size.height > 0) {
+    _initialHeightReported = YES;
     [delegate contentWrapper:self didChangeContentHeight:self.frame.size.height];
   }
 }

From 8716e74646ef52ccf64a3023a531f07067a9eb7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 14:01:16 +0200
Subject: [PATCH 11/16] Update type doc

---
 .../gamma/modals/form-sheet/FormSheet.types.ts       | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/components/gamma/modals/form-sheet/FormSheet.types.ts b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
index 0730af3465..c804be1cb3 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.types.ts
+++ b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
@@ -18,10 +18,16 @@ export interface FormSheetProps {
    */
   isOpen: boolean;
 
-  // TODO: @t0maboro - update description after implementing fitToContents
   /**
-   * @summary An array of fractional screen heights (ranging from `0.0` to `1.0`) that define
-   * the resting positions of the sheet.
+   * @summary Defines the resting positions of the sheet.
+   *
+   * This can be either an array of fractional screen heights (ranging from `0.0` to `1.0`)
+   * or the `'fitToContents'` string literal.
+   *
+   * - **Fractional heights:** The sheet will snap to these specific height proportions.
+   * - **`'fitToContents'`:** The sheet automatically calculates its height to wrap its content.
+   *   It will dynamically animate to adapt to any internal layout changes.
+   *  *(Note: `fitToContents` is supported on iOS 16+. On iOS 15, it falls back to a medium detent).*
    *
    * On iOS, these map directly to `UISheetPresentationController` detents.
    * If an empty array is provided, it defaults to a single large detent.

From 009f8206ebcfe838ba75ecc0ef87a775927e7059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 14:24:38 +0200
Subject: [PATCH 12/16] fix

---
 .../modals/form-sheet/RNSFormSheetDetentResolver.mm   | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
index 1856b64191..b8bd9c155a 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetDetentResolver.mm
@@ -73,9 +73,14 @@ @implementation RNSFormSheetDetentResolver
                           customDetentWithIdentifier:ident
                                             resolver:^CGFloat(
                                                 id<UISheetPresentationControllerDetentResolutionContext> context) {
-                                              CGFloat currentHeight =
-                                                  weakProvider ? [weakProvider contentHeight] : -1.0;
-                                              return currentHeight;
+                                              CGFloat currentHeight = weakProvider ? [weakProvider contentHeight] : 0.0;
+
+                                              // Safe fallback for uncalculated layout or deallocated provider
+                                              if (currentHeight <= 0.0) {
+                                                currentHeight = context.maximumDetentValue;
+                                              }
+
+                                              return MIN(context.maximumDetentValue, currentHeight);
                                             }]];
       } else {
         [nativeDetents

From 8d36db44c19d9630a98f0057532577427d630b9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 14:25:47 +0200
Subject: [PATCH 13/16] add missing import

---
 .../modals/form-sheet/RNSFormSheetContentWrapperDelegate.h      | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
index 5d0bd7cbc4..b893e602b7 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperDelegate.h
@@ -1,5 +1,7 @@
 #pragma once
 
+#import <UIKit/UIKit.h>
+
 @class RNSFormSheetContentWrapperComponentView;
 
 NS_ASSUME_NONNULL_BEGIN

From 914dcb29c46722cbd5180a7d4cf114f72a85d648 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Mon, 25 May 2026 14:26:25 +0200
Subject: [PATCH 14/16] remove dead code

---
 .../modals/form-sheet/RNSFormSheetContentWrapperComponentView.h | 2 --
 1 file changed, 2 deletions(-)

diff --git a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
index 88447defe8..71983b6a43 100644
--- a/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
+++ b/ios/gamma/modals/form-sheet/RNSFormSheetContentWrapperComponentView.h
@@ -7,8 +7,6 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface RNSFormSheetContentWrapperComponentView : RNSReactBaseView
 
-@property (nonatomic, weak, nullable) id<RNSFormSheetContentWrapperDelegate> delegate;
-
 @end
 
 NS_ASSUME_NONNULL_END

From 6121c7d64c45690c4eabb2640c3b232ce6db941d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Tue, 26 May 2026 13:20:08 +0200
Subject: [PATCH 15/16] Render ContentWrapper only for fitToContents

---
 .../gamma/modals/form-sheet/FormSheet.tsx        | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/components/gamma/modals/form-sheet/FormSheet.tsx b/src/components/gamma/modals/form-sheet/FormSheet.tsx
index 7ffaff1b3e..ac0819e222 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.tsx
+++ b/src/components/gamma/modals/form-sheet/FormSheet.tsx
@@ -45,14 +45,14 @@ export function FormSheet(props: FormSheetProps) {
       largestUndimmedDetentIndex={resolvedUndimmedDetentIndex}
       preferredCornerRadius={nativeCornerRadius}
       {...rest}>
-      <FormSheetContentWrapperNativeComponent
-        style={
-          isFitToContents
-            ? styles.absoluteWithNoBottom
-            : StyleSheet.absoluteFill
-        }>
-        {children}
-      </FormSheetContentWrapperNativeComponent>
+      {isFitToContents ? (
+        <FormSheetContentWrapperNativeComponent
+          style={styles.absoluteWithNoBottom}>
+          {children}
+        </FormSheetContentWrapperNativeComponent>
+      ) : (
+        children
+      )}
     </FormSheetHostNativeComponent>
   );
 }

From 7fbdaf268cbfad840581339f195e04400c3b2716 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Boro=C5=84?= <tomasz.boron@swmansion.com>
Date: Tue, 26 May 2026 12:24:51 +0200
Subject: [PATCH 16/16] Add support for backgroundComponent

---
 .../single-feature-tests/form-sheet/index.ts  |   2 +
 .../index.tsx                                 | 232 ++++++++++++++++++
 .../scenario-description.ts                   |  11 +
 .../scenario.md                               |  79 ++++++
 .../gamma/modals/form-sheet/FormSheet.tsx     |   8 +-
 .../modals/form-sheet/FormSheet.types.ts      |  12 +
 6 files changed, 343 insertions(+), 1 deletion(-)
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/index.tsx
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario-description.ts
 create mode 100644 apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario.md

diff --git a/apps/src/tests/single-feature-tests/form-sheet/index.ts b/apps/src/tests/single-feature-tests/form-sheet/index.ts
index 9f545bfbac..08779561ac 100644
--- a/apps/src/tests/single-feature-tests/form-sheet/index.ts
+++ b/apps/src/tests/single-feature-tests/form-sheet/index.ts
@@ -1,5 +1,6 @@
 import type { ScenarioGroup } from '@apps/tests/shared/helpers';
 import TestFormSheetBase from './test-form-sheet-base-ios';
+import TestFormSheetBackgroundComponent from './test-form-sheet-background-component-ios';
 import TestFormSheetExpandScrollView from './test-form-sheet-expand-scroll-view-ios';
 import TestFormSheetFitToContents from './test-form-sheet-fit-to-contents-ios';
 import TestFormSheetGrabberVisible from './test-form-sheet-grabber-visible-ios';
@@ -11,6 +12,7 @@ import TestFormSheetPresentationState from './test-form-sheet-presentation-state
 
 const scenarios = {
   TestFormSheetBase,
+  TestFormSheetBackgroundComponent,
   TestFormSheetExpandScrollView,
   TestFormSheetFitToContents,
   TestFormSheetGrabberVisible,
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/index.tsx b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/index.tsx
new file mode 100644
index 0000000000..49564a2590
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/index.tsx
@@ -0,0 +1,232 @@
+import React, { useState } from 'react';
+import {
+  Button,
+  StyleSheet,
+  Text,
+  View,
+  Image,
+  Dimensions,
+  TouchableOpacity,
+} from 'react-native';
+import { FormSheet } from 'react-native-screens/experimental';
+import { scenarioDescription } from './scenario-description';
+import { createScenario } from '@apps/tests/shared/helpers';
+import { Colors } from '@apps/shared/styling';
+
+const SCREEN_WIDTH = Dimensions.get('window').width;
+
+type BackgroundType = 'none' | 'solid' | 'composed' | 'image';
+
+export function App() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [bgType, setBgType] = useState<BackgroundType>('image');
+
+  const handleDismiss = () => {
+    setIsOpen(false);
+  };
+
+  const SolidBackground = (
+    <View
+      style={[
+        StyleSheet.absoluteFill,
+        { backgroundColor: Colors.PurpleLight100 },
+      ]}
+    />
+  );
+
+  const ComposedBackground = (
+    <View
+      style={[
+        StyleSheet.absoluteFill,
+        { backgroundColor: Colors.NavyLight80 },
+      ]}>
+      <View style={styles.composedTopBar} />
+      <View style={styles.composedBottomBar} />
+    </View>
+  );
+
+  const ImageBackground = (
+    <Image
+      source={{
+        uri: 'https://fastly.picsum.photos/id/541/900/600.jpg?hmac=W6n9QTOEWat4-wHywp8az4ZqvcDzUMWWR1XDq3kS9sI',
+        height: 600,
+        width: SCREEN_WIDTH,
+      }}
+      style={StyleSheet.absoluteFill}
+    />
+  );
+
+  const renderBackground = () => {
+    switch (bgType) {
+      case 'solid':
+        return SolidBackground;
+      case 'composed':
+        return ComposedBackground;
+      case 'image':
+        return ImageBackground;
+      case 'none':
+      default:
+        return undefined;
+    }
+  };
+
+  const isDarkBg = bgType !== 'none';
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>FormSheet Background</Text>
+
+      <View style={styles.controlsContainer}>
+        <Text style={styles.controlsLabel}>Select Background Type:</Text>
+        <View style={styles.buttonRow}>
+          {(['none', 'solid', 'composed', 'image'] as BackgroundType[]).map(
+            type => (
+              <TouchableOpacity
+                key={type}
+                style={[
+                  styles.optionButton,
+                  bgType === type && styles.optionButtonActive,
+                ]}
+                onPress={() => setBgType(type)}>
+                <Text
+                  style={[
+                    styles.optionText,
+                    bgType === type && styles.optionTextActive,
+                  ]}>
+                  {type.toUpperCase()}
+                </Text>
+              </TouchableOpacity>
+            ),
+          )}
+        </View>
+      </View>
+
+      <View style={styles.spacing} />
+
+      <Button
+        title="Open FormSheet"
+        color={Colors.primary}
+        onPress={() => setIsOpen(true)}
+      />
+
+      <FormSheet
+        isOpen={isOpen}
+        onNativeDismiss={handleDismiss}
+        detents='fitToContents'
+        backgroundComponent={renderBackground()}>
+        <View style={styles.sheetContent}>
+          <Text style={[styles.sheetTitle, isDarkBg && styles.textWhite]}>
+            Custom Background
+          </Text>
+
+          <Text style={[styles.description, isDarkBg && styles.textWhite]}>
+            Currently displaying: {bgType.toUpperCase()}. The background should
+            stretch to fill the entire native sheet, including the bottom safe
+            area.
+          </Text>
+
+          <View style={styles.spacing} />
+
+          <Button
+            title="Dismiss from JS"
+            color={isDarkBg ? Colors.White : Colors.primary}
+            onPress={handleDismiss}
+          />
+        </View>
+      </FormSheet>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: Colors.offBackground,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    marginBottom: 20,
+    color: Colors.text,
+  },
+  controlsContainer: {
+    paddingHorizontal: 16,
+    width: '100%',
+    alignItems: 'center',
+  },
+  controlsLabel: {
+    fontSize: 14,
+    color: Colors.text,
+    marginBottom: 8,
+  },
+  buttonRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: 8,
+  },
+  optionButton: {
+    paddingVertical: 6,
+    paddingHorizontal: 12,
+    borderRadius: 16,
+    borderWidth: 1,
+    borderColor: Colors.primary,
+  },
+  optionButtonActive: {
+    backgroundColor: Colors.primary,
+  },
+  optionText: {
+    fontSize: 12,
+    color: Colors.primary,
+    fontWeight: '600',
+  },
+  optionTextActive: {
+    color: Colors.White,
+  },
+  sheetContent: {
+    padding: 24,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  sheetTitle: {
+    fontSize: 22,
+    fontWeight: '600',
+    marginBottom: 12,
+    color: Colors.text,
+  },
+  description: {
+    fontSize: 16,
+    textAlign: 'center',
+    color: Colors.text,
+    paddingHorizontal: 16,
+  },
+  textWhite: {
+    color: Colors.White,
+    textShadowColor: Colors.NavyLightTransparent,
+    textShadowOffset: { width: 0, height: 1 },
+    textShadowRadius: 2,
+  },
+  spacing: {
+    height: 24,
+  },
+  composedTopBar: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    height: 12,
+    backgroundColor: Colors.GreenLight100,
+  },
+  composedBottomBar: {
+    position: 'absolute',
+    bottom: 0,
+    left: 0,
+    right: 0,
+    height: 40,
+    backgroundColor: Colors.RedLight100,
+  },
+});
+
+export default createScenario(App, scenarioDescription);
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario-description.ts b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario-description.ts
new file mode 100644
index 0000000000..892ebf2c1c
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario-description.ts
@@ -0,0 +1,11 @@
+import type { ScenarioDescription } from '@apps/tests/shared/helpers';
+
+export const scenarioDescription: ScenarioDescription = {
+  name: 'Background component',
+  key: 'test-form-sheet-background-component-ios',
+  details:
+    'Allows to test the custom background component rendering of the FormSheet.',
+  platforms: ['ios'],
+  e2eCoverage: 'tbd',
+  smokeTest: false,
+};
diff --git a/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario.md b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario.md
new file mode 100644
index 0000000000..0836f78648
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/form-sheet/test-form-sheet-background-component-ios/scenario.md
@@ -0,0 +1,79 @@
+# Test Scenario: Background component
+
+## Details
+
+**Description:** Verify the `backgroundComponent` functionality of the `FormSheet` component. This test ensures that the custom background component correctly renders beneath the content layer and fully extends to cover the entire native bounds of the sheet, including the un-collapsible bottom safe area injected by UIKit.
+
+**OS test creation version:** iOS: 18.6 and 26.4
+
+## E2E test
+
+Other: Planned, but will be implemented separately.
+
+## Prerequisites
+
+- iOS device or simulator
+
+## Steps
+
+### Baseline
+
+1. Launch the app and navigate to the **Background component** screen.
+
+- [ ] Expected: Content with the button "Open FormSheet" and background selection controls is shown.
+
+---
+
+### Verification: "NONE" Background
+
+2. Select the "NONE" background type and tap the "Open FormSheet" button.
+
+- [ ] Expected: The FormSheet opens smoothly.
+- [ ] Expected: The background is the default system color (e.g., white or dark depending on the theme).
+
+3. Tap the "Dismiss from JS" button.
+
+- [ ] Expected: The FormSheet dismisses smoothly.
+
+---
+
+### Verification: "SOLID" Background
+
+4. Select the "SOLID" background type and tap the "Open FormSheet" button.
+
+- [ ] Expected: The FormSheet opens smoothly.
+- [ ] Expected: A solid purple background is visible behind the text content.
+- [ ] Expected: The purple background extends all the way to the absolute bottom edge of the screen.
+
+5. Tap the "Dismiss from JS" button.
+
+- [ ] Expected: The FormSheet dismisses smoothly.
+
+---
+
+### Verification: "COMPOSED" Background
+
+6. Select the "COMPOSED" background type and tap the "Open FormSheet" button.
+
+- [ ] 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.
+
+7. Tap the "Dismiss from JS" button.
+
+- [ ] Expected: The FormSheet dismisses smoothly.
+
+---
+
+### Verification: "IMAGE" Background
+
+8. Select the "IMAGE" background type and tap the "Open FormSheet" button.
+
+- [ ] Expected: The FormSheet opens smoothly.
+- [ ] Expected: An image background is visible behind the text content.
+- [ ] Expected: The image fully covers the native sheet bounds, extending completely under the navigation bar.
+
+9. Tap the "Dismiss from JS" button.
+
+- [ ] Expected: The FormSheet dismisses smoothly and returns the user to the underlying main screen.
diff --git a/src/components/gamma/modals/form-sheet/FormSheet.tsx b/src/components/gamma/modals/form-sheet/FormSheet.tsx
index ac0819e222..b33a63e48f 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.tsx
+++ b/src/components/gamma/modals/form-sheet/FormSheet.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import { StyleSheet } from 'react-native';
+import { StyleSheet, View } from 'react-native';
 import FormSheetHostNativeComponent from '../../../../fabric/gamma/modals/form-sheet/FormSheetHostNativeComponent';
 import FormSheetContentWrapperNativeComponent from '../../../../fabric/gamma/modals/form-sheet/FormSheetContentWrapperNativeComponent';
 import type { FormSheetProps } from './FormSheet.types';
@@ -12,6 +12,7 @@ import {
 
 export function FormSheet(props: FormSheetProps) {
   const {
+    backgroundComponent,
     children,
     detents,
     initialDetentIndex,
@@ -45,6 +46,11 @@ export function FormSheet(props: FormSheetProps) {
       largestUndimmedDetentIndex={resolvedUndimmedDetentIndex}
       preferredCornerRadius={nativeCornerRadius}
       {...rest}>
+      {backgroundComponent !== undefined && (
+        <View style={StyleSheet.absoluteFill} pointerEvents="none">
+          {backgroundComponent}
+        </View>
+      )}
       {isFitToContents ? (
         <FormSheetContentWrapperNativeComponent
           style={styles.absoluteWithNoBottom}>
diff --git a/src/components/gamma/modals/form-sheet/FormSheet.types.ts b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
index c804be1cb3..7ef96846e8 100644
--- a/src/components/gamma/modals/form-sheet/FormSheet.types.ts
+++ b/src/components/gamma/modals/form-sheet/FormSheet.types.ts
@@ -103,6 +103,18 @@ export interface FormSheetProps {
    */
   prefersScrollingExpandsWhenScrolledToEdge?: boolean | undefined;
 
+  /**
+   * @summary A custom React component to render as the background of the sheet.
+   *
+   * 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.
+   *
+   * @platform ios
+   */
+  backgroundComponent?: React.ReactNode | undefined;
+
   // Events
   /**
    * @summary Called when the sheet is dismissed natively.