update and unify removeClippedSubviews prop description (facebook#4818)

Simek · web-flow · commit a72074fb27c6 · 2025-09-23T16:33:55.000+02:00
diff --git a/docs/flatlist.md b/docs/flatlist.md
@@ -638,12 +638,12 @@ Set this true while waiting for new data from a refresh.
 
 ### `removeClippedSubviews`
 
-This may improve scroll performance for large lists. On Android the default value is `true`.
-
 :::warning
-May have bugs (missing content) in some circumstances - use at your own risk.
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
 :::
 
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
+
 | Type    |
 | ------- |
 | boolean |
diff --git a/docs/optimizing-flatlist-configuration.md b/docs/optimizing-flatlist-configuration.md
@@ -1,6 +1,6 @@
 ---
 id: optimizing-flatlist-configuration
-title: Optimizing Flatlist Configuration
+title: Optimizing FlatList Configuration
 ---
 
 ## Terms
@@ -23,9 +23,9 @@ Here are a list of props that can help to improve `FlatList` performance:
 
 ### `removeClippedSubviews`
 
-| Type    | Default |
-| ------- | ------- |
-| Boolean | False   |
+| Type    | Default                              |
+| ------- | ------------------------------------ |
+| Boolean | `true` on Android, otherwise `false` |
 
 If `true`, views that are outside of the viewport are detached from the native view hierarchy.
 
@@ -148,7 +148,6 @@ const renderItem = useCallback(({item}) => (
 
 return (
   // ...
-
   <FlatList data={items} renderItem={renderItem} />;
   // ...
 );
diff --git a/docs/scrollview.md b/docs/scrollview.md
@@ -554,11 +554,15 @@ See [RefreshControl](refreshcontrol).
 
 ### `removeClippedSubviews`
 
-Experimental: When `true`, offscreen child views (whose `overflow` value is `hidden`) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.
+:::warning
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
+:::
 
-| Type | Default |
-| ---- | ------- |
-| bool | `false` |
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
+
+| Type    |
+| ------- |
+| boolean |
 
 ---
 
diff --git a/docs/sectionlist.md b/docs/sectionlist.md
@@ -253,11 +253,11 @@ Set this true while waiting for new data from a refresh.
 Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
 :::
 
-This may improve scroll performance for large lists.
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
 
-| Type    | Default |
-| ------- | ------- |
-| boolean | `false` |
+| Type    |
+| ------- |
+| boolean |
 
 ---
 
diff --git a/docs/virtualizedlist.md b/docs/virtualizedlist.md
@@ -521,12 +521,12 @@ Set this true while waiting for new data from a refresh.
 
 ### `removeClippedSubviews`
 
-This may improve scroll performance for large lists.
-
 :::warning
 Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
 :::
 
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
+
 | Type    |
 | ------- |
 | boolean |
diff --git a/website/versioned_docs/version-0.81/flatlist.md b/website/versioned_docs/version-0.81/flatlist.md
@@ -638,9 +638,11 @@ Set this true while waiting for new data from a refresh.
 
 ### `removeClippedSubviews`
 
-This may improve scroll performance for large lists. On Android the default value is `true`.
+:::warning
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
+:::
 
-> Note: May have bugs (missing content) in some circumstances - use at your own risk.
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
 
 | Type    |
 | ------- |
diff --git a/website/versioned_docs/version-0.81/optimizing-flatlist-configuration.md b/website/versioned_docs/version-0.81/optimizing-flatlist-configuration.md
@@ -1,6 +1,6 @@
 ---
 id: optimizing-flatlist-configuration
-title: Optimizing Flatlist Configuration
+title: Optimizing FlatList Configuration
 ---
 
 ## Terms
@@ -23,9 +23,9 @@ Here are a list of props that can help to improve `FlatList` performance:
 
 ### removeClippedSubviews
 
-| Type    | Default |
-| ------- | ------- |
-| Boolean | False   |
+| Type    | Default                              |
+| ------- | ------------------------------------ |
+| Boolean | `true` on Android, otherwise `false` |
 
 If `true`, views that are outside of the viewport are detached from the native view hierarchy.
 
@@ -148,7 +148,6 @@ const renderItem = useCallback(({item}) => (
 
 return (
   // ...
-
   <FlatList data={items} renderItem={renderItem} />;
   // ...
 );
diff --git a/website/versioned_docs/version-0.81/scrollview.md b/website/versioned_docs/version-0.81/scrollview.md
@@ -554,11 +554,15 @@ See [RefreshControl](refreshcontrol).
 
 ### `removeClippedSubviews`
 
-Experimental: When `true`, offscreen child views (whose `overflow` value is `hidden`) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.
+:::warning
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
+:::
 
-| Type | Default |
-| ---- | ------- |
-| bool | `false` |
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
+
+| Type    |
+| ------- |
+| boolean |
 
 ---
 
diff --git a/website/versioned_docs/version-0.81/sectionlist.md b/website/versioned_docs/version-0.81/sectionlist.md
@@ -249,13 +249,15 @@ Set this true while waiting for new data from a refresh.
 
 ### `removeClippedSubviews`
 
-> Note: may have bugs (missing content) in some circumstances - use at your own risk.
+:::warning
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
+:::
 
-This may improve scroll performance for large lists.
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
 
-| Type    | Default |
-| ------- | ------- |
-| boolean | `false` |
+| Type    |
+| ------- |
+| boolean |
 
 ---
 
diff --git a/website/versioned_docs/version-0.81/virtualizedlist.md b/website/versioned_docs/version-0.81/virtualizedlist.md
@@ -519,9 +519,11 @@ Set this true while waiting for new data from a refresh.
 
 ### `removeClippedSubviews`
 
-This may improve scroll performance for large lists.
+:::warning
+Using this property may lead to bugs (missing content) in some circumstances - use at your own risk.
+:::
 
-> Note: May have bugs (missing content) in some circumstances - use at your own risk.
+When `true`, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is `true`.
 
 | Type    |
 | ------- |
