Diagnose & Fix Janky FlatList Rendering in React Native

Recognizable Symptoms

When you scroll a FlatList you may notice:

• Sudden frame‑rate drops (30 fps → 10 fps)
• Blank or flickering rows during fast flings
• Long initial paint when the list has >50 items, especially with images
• JS thread blocked for >16 ms on every scroll tick

Common Causes & Diagnostic Map

Symptom	Likely Cause
Stutter on scroll	Inline renderItem recreates component each render
Blank cells in fast flings	Unstable keyExtractor (e.g., array index)
Slow first paint	Large initialNumToRender or windowSize
Inconsistent scrollToIndex	Missing getItemLayout for fixed‑height rows
Re‑render on parent state change	Rows receive new object/array props each render

Ordered Diagnostic Checklist

1. Confirm the list is the bottleneck
   • Open the dev menu → Perf Monitor and record JS/UI frame rates while scrolling.
   • If frame drops are concentrated in the FlatList area, proceed.
2. Audit renderItem definition
   • Is it declared inline inside render or return?
   • Does it create new functions or objects per row?
   • Move it outside the render method or wrap the row component with React.memo.
3. Verify keyExtractor stability
   • Return a unique, immutable value (e.g., item.id).
   • Avoid index‑based keys when rows can reorder or prepend.
4. Check parent state updates
   • Does a state change in a parent component cause the entire list to re‑render?
   • Use React.memo or useMemo on the list wrapper to prevent unnecessary re‑renders.
5. Measure windowing & clipping props
   • Default windowSize is 21 viewports; maxToRenderPerBatch is 10.
   • For large lists, try initialNumToRender={10}, maxToRenderPerBatch={20}, windowSize={7}.
   • Toggle removeClippedSubviews only after confirming no disappearing content on Android.
6. Implement getItemLayout if row height is fixed
   • Example:

     const getItemLayout = (data, index) => ({
       length: 80,
       offset: 80 * index,
       index,
     });

   • Allows FlatList to skip measurement and speeds up scrollToIndex.

Targeted Fixes for Each Finding

• Inline renderItem → Hoist to a separate memoized component:

  const Row = React.memo(({item}) => {
    return {item.title};
  });
  
  // In render
  renderItem={({item}) => }

• Unstable keys →

  keyExtractor={item => item.id.toString()}

• Large windowing defaults → adjust as shown in the checklist.
• Missing getItemLayout → add when rows are uniform height.
• Re‑renders on parent state change → wrap the FlatList in React.memo or move the list into a child component that only receives data and refreshing props.

Verification Steps

1. After each tweak, re‑open Perf Monitor and scroll a fast‑fling; look for JS frame drops dropping below 10 ms per frame.
2. Insert a counter: console.count('RowRender'); inside the row component. The count should not increase on unrelated parent state updates.
3. Test on a low‑end physical Android device; simulator performance can be misleading.
4. Run a quick benchmark: react-native run-android --variant=release and use Android Profiler to confirm UI thread stays under 16 ms.

Escalation Criteria

• If memoization and windowing tweaks fail to bring frame rates above 60 fps during typical usage, proceed to profiling.
• Use Hermes profiler or Flipper to identify heavy JS work per scroll tick.
• Consider swapping to FlashList (a recycler‑style list) if the list contains deeply nested heterogeneous rows or large images.
• As a last resort, split the list into smaller chunks or lazy‑load heavy content outside of the list.

Practical Example

Below is a minimal FlatList that applies the above fixes:

import React, {useMemo} from 'react';
import {FlatList, Text, View} from 'react-native';

const Row = React.memo(({item}) => (
  
    {item.title}
  
));

const MyList = ({data}) => {
  const keyExtractor = useMemo(() => (item) => item.id.toString(), []);

  const getItemLayout = useMemo(() => (data, index) => ({
    length: 80,
    offset: 80 * index,
    index,
  }), []);

  return (
     }
      initialNumToRender={10}
      maxToRenderPerBatch={20}
      windowSize={7}
      removeClippedSubviews={true}
      getItemLayout={getItemLayout}
    />
  );
};

Limitations & Caveats

• Prop defaults may differ between React Native 0.72 and 0.74; check your react-native version docs.
• Enabling removeClippedSubviews can hide content that uses absolute positioning or complex transforms on Android.
• FlashList is a third‑party library; evaluate its maintenance status before adding it to production.
• Memoization only helps if row props are referentially stable; avoid passing new object literals each render.

Conclusion

By systematically verifying the list as the bottleneck, stabilizing keys, hoisting render logic, tuning windowing, and, when necessary, providing getItemLayout, most jank in FlatList can be eliminated. Use the Perf Monitor and console counters to confirm each change addresses the real issue before escalating to deeper profiling or alternative list implementations.