docs: clarify FlatList extraData prop and PureComponent behavior (fixes #5216)

docs/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.77/flatlist.md

@@ -151,7 +151,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.78/flatlist.md

@@ -151,7 +151,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.79/flatlist.md

@@ -151,7 +151,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.80/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.81/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.82/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.83/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.84/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.85/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.86/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>

website/versioned_docs/version-0.87/flatlist.md

@@ -149,7 +149,7 @@ To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop.
 
 More complex, selectable example below.
 
-- By passing `extraData={selectedId}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
+- Passing `extraData={selectedId}` to `FlatList` ensures that `FlatList` re-renders when `selectedId` changes. Because `FlatList` implements `PureComponent`, it only re-renders if its props change. While `renderItem` in this example is recreated on each render because it is defined inline, passing `extraData` is essential whenever `renderItem` has a stable reference (such as when memoized or defined outside the component) so that `FlatList` knows that an external dependency has updated.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>