In a React Native FlatList news feed, new stories are prepended while a reader is mid-list; why does content jump, and how does maintainVisibleContentPosition help?

## Why prepending moves the content A React Native `ScrollView` - and `FlatList`, which renders one - remembers where you are as a **content offset**: the distance from the top of the content to the top of the viewport. That number does not change when the content changes. Suppose a reader is 3,000 points into a news feed, looking at story 12, and the app prepends five breaking stories that are 400 points tall each. The offset is still 3,000, but story 12 now starts 2,000 points lower. The reader is suddenly looking at story 7 without having touched the screen. Appending at the end does not have this problem, because nothing above the viewport moved. The jump is specific to **inserting above what is visible**: live feeds, "new stories" updates and chats that load history upward. ## maintainVisibleContentPosition `maintainVisibleContentPosition` is a `ScrollView` prop that `FlatList` passes through. Its value is an object: | Field | Meaning | |---|---| | `minIndexForVisible` | The anchor rule: the first visible child **at or beyond** this index keeps its position. `0` is common; `1` skips a loading row or banner at index 0. | | `autoscrollToTopThreshold` | Optional: if the reader was within this distance of the top before the adjustment, the view then scrolls to the top so the new content comes into view. | The adjustment happens on the native side: after the insert, the scroll view moves its own offset by however much the anchor view moved. The reader keeps reading story 12, and the five new stories sit above it, off screen. The threshold field covers the other reader - the one already at the top, who wants to see the new stories rather than stay pinned to what was the first row. ## What FlatList adds on top `FlatList` is virtualized, so there is a second problem beyond the native offset: its **render window** is a range of indices, and after five rows are prepended those indices point at different items. In React Native 0.87, `VirtualizedList` handles this when the prop is set: - It remembers the **key** of the item at `minIndexForVisible`. When the key at that index changes, it looks up the old key in the new data and shifts the render window by the number of rows inserted, so it keeps rendering the cells that are actually on screen. - Because the lookup is by key, **stable keys are required**. With index keys, the key at the anchor index is the same string before and after the insert, so the window is never shifted. - While the native adjustment is pending, the scroll position JavaScript holds is stale, so the list holds back `onStartReached` and `onEndReached` until the next scroll event arrives. - It adds one to `minIndexForVisible` when a `ListHeaderComponent` is present, because the header occupies the first child slot. ## Caveats from the docs 1. **Do not reorder.** The docs warn that reordering elements with the prop enabled will probably cause jumpiness, with no plans to fix it. Moving a story to the top as "updated" is a reorder. 2. **Visibility is approximate.** It uses each child's content offset and frame origin, so transforms, occlusion and similar effects are not taken into account. 3. **It moves the position, not the reader's attention.** The reader is not told that stories arrived above; that is a product decision layered on top. ## Patterns for a live news feed - **Silent insert with anchoring** - prepend and let `maintainVisibleContentPosition` hold the reader in place, with `autoscrollToTopThreshold` for readers already at the top. - **Buffer and announce** - hold incoming stories aside, show a "new stories" pill, and prepend and scroll to the top only when it is tapped. This avoids inserts during reading entirely. - **Chat-style threads** - an inverted list handles loading history at the logical end without this prop, but a new message arriving at index 0 while the reader is scrolled into history is exactly the prepend case again. ## Versions and the FlashList alternative In the React Native 0.87 docs the prop carries no platform label, so it is documented for both iOS and Android. FlashList v2 has its own `maintainVisibleContentPosition`, which is **on by default** there and adds options such as `startRenderingFromBottom` for chat screens; its docs suggest raising `drawDistance` when many rows are added at the top.