React Native FlatList warns that it is slow to update and scrolls with lag
VirtualizedList: You have a large list that is slow to updateShort answer
React Native logs this message when scroll events arrive more than 500 ms apart on a list longer than five screens. The list is busy on the JS thread. Memoize the row component, keep renderItem stable, pass changing outside data through extraData, and give the list a key and fixed row size if you can.
Fix it fast
1Find out which cause you have
Note which rule triggers it: the message appears once per list after two slow scroll events on content longer than five viewports. Then check what your row does on every render.
grep -n "renderItem" -r src/ | head grep -n "keyExtractor\|getItemLayout\|extraData" -r src/ | head2Match what you see, then jump to its fix
- 1
Scrolling stutters and the profiler shows all visible rows rendering again on each state change in the parent.Every row re-renders because renderItem and the row are not memoizedFix - 2
Rows show old state after a change, or you worked around that by creating new arrays on every render.The list does not re-render, or re-renders too much, because of extraDataFix - 3
Fast scrolling shows blank areas, and jumping with scrollToIndex or initialScrollIndex is janky.The list computes row sizes and keys the slow wayFix - 4
The first screen takes long to appear, or each scroll step blocks the JS thread.Window and batch settings render too much at onceFix
- 1
What does the error look like?
VirtualizedList: You have a large list that is slow to updatemake sure your renderItem function renders components that follow React performance best practices like PureComponent, shouldComponentUpdate, etc.
Cause 1 of 4
Every row re-renders because renderItem and the row are not memoized
1Check
Look for an inline arrow function in the renderItem prop, or a row component that is not wrapped in memo. Both make React redo the work for rows that did not change.
grep -n -A3 "renderItem=" src/screens/*.tsx2Fix
Define renderItem once with useCallback and wrap the row component in React.memo so it only renders when its own props change. Keep each row small.
const Row = memo(({ title }: { title: string }) => (
<View><Text>{title}</Text></View>
));
const renderItem = useCallback(
({ item }) => <Row title={item.title} />,
[],
);
<FlatList data={items} renderItem={renderItem} keyExtractor={item => item.id} />3Verify
Reload the app and scroll fast through the list. The message should not return.
npx react-native start --reset-cacheConfirmed by reactnative.dev
Cause 2 of 4
The list does not re-render, or re-renders too much, because of extraData
1Check
The list is a PureComponent: it skips rendering when its props are shallow-equal. If renderItem reads state that is not in data, such as a selected id, the list has no way to know it changed.
grep -n "selected\|extraData" src/screens/*.tsx2Fix
Pass the outside value as extraData and treat it immutably. Do not rebuild the whole data array just to force an update.
<FlatList
data={items}
extraData={selectedId}
renderItem={renderItem}
keyExtractor={item => item.id}
/>3Verify
Change the selection. Only the affected rows should update and scrolling stays smooth.
# open the React DevTools profiler and record one selection changeConfirmed by reactnative.dev
Cause 3 of 4
The list computes row sizes and keys the slow way
1Check
Without getItemLayout the list measures each row asynchronously. keyExtractor is used for caching and for tracking item re-ordering.
grep -n "getItemLayout\|keyExtractor" -r src/2Fix
Set keyExtractor on every list. If all rows have the same height, add getItemLayout so measuring is skipped. If rows vary in size, do not guess lengths.
const ROW_HEIGHT = 64;
<FlatList
data={items}
keyExtractor={item => item.id}
getItemLayout={(_, index) => ({
length: ROW_HEIGHT,
offset: ROW_HEIGHT * index,
index,
})}
renderItem={renderItem}
/>3Verify
Scroll quickly and call scrollToIndex on a far row: no blank gap and no jump.
# test on a release build or a real device, not only the dev buildConfirmed by reactnative.dev
Cause 4 of 4
Window and batch settings render too much at once
1Check
initialNumToRender defaults to 10 and maxToRenderPerBatch to 10. windowSize defaults to 21, which renders about ten screens above and below the viewport.
grep -n "windowSize\|initialNumToRender\|maxToRenderPerBatch" -r src/2Fix
Set initialNumToRender to about what fills one screen, and lower windowSize to save memory. A lower windowSize can show blank areas in fast scrolls, so change one value at a time.
<FlatList
data={items}
renderItem={renderItem}
keyExtractor={item => item.id}
initialNumToRender={8}
windowSize={7}
/>3Verify
Compare first render time and fast-scroll behaviour on the slowest phone you support.
# keep the value that gives smooth scrolling with no blank areasConfirmed by reactnative.dev
How do I stop it coming back?
- Keep list rows basic: little nesting, little logic, small images.
- Wrap row components in memo and define renderItem outside the JSX.
- Always set keyExtractor, and getItemLayout when row size is fixed.
- Judge list speed on a release build, not the dev build.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Android build stops at processDebugManifest in a React Native app
Manifest merger failed
processDebugManifest is the step that merges your AndroidManifest.xml with the manifests of every library.
2 causes, each with a fixMobile apps
Running pod on a React Native project fails with can't find gem cocoapods
can't find gem cocoapods (>= 0.a) with executable pod
The pod command exists, but the Ruby that is running it has no CocoaPods gem.
3 causes, each with a fixMobile apps
React Native Android build cannot find the foojay-resolver-convention plugin
Plugin [id: 'org.gradle.toolchains.foojay-resolver-convention'] was not found in any of the following sources:
The foojay plugin is a settings plugin that Gradle downloads from the Plugin Portal.
3 causes, each with a fixMobile apps
Kotlin and Java compile to different JVM targets in a React Native Android build
'compileJava' task (current target is 1.8) and 'compileKotlin' task (current target is 11)
Gradle refuses to build when the Java task and the Kotlin task target different JVM versions.
3 causes, each with a fixMobile apps
Gradle cannot run node in a React Native Android build
Process 'command 'node'' finished with non-zero exit value 1
The React Native Gradle plugin starts node for bundling.
3 causes, each with a fixMobile apps
The Android emulator opens the app but never connects to Metro or Expo
Metro bundler ECONNREFUSED 127.0.0.1:19001
When the emulator cannot reach Metro, first prove each side on its own: adb sees the emulator, and Metro listens on its port.
4 causes, each with a fix