Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 71 ยท Lists

Fast Lists: Virtualization and Tuning

Make React Native lists smooth: how virtualization works, windowSize, getItemLayout, memoized rows, stable callbacks, removeClippedSubviews and FlashList.

A list that is smooth with 20 rows can stutter with 2,000. The cause is nearly always the same: too much work per scroll frame. The phone has about 16 milliseconds per frame at 60 frames per second (8 ms at 120), and everything your JavaScript does while scrolling competes for that budget.

In this lesson you learn what virtualization is, which FlatList props control it, how to stop rows from re-rendering for no reason, when getItemLayout helps, and when a different list component (FlashList) is worth installing. The general React ideas are in virtualization and memo; here we apply them to mobile.

Read-only and stand-in. The real FlatList and FlashList need native views, so their code is shown in plain blocks. The TryIts simulate two things in plain JavaScript: the window of rows a virtualized list keeps mounted, and how many row renders memoization saves. The numbers come from the simulation, not from a device.

What virtualization means

A virtualized list does not mount every row. It mounts the rows in a window around the visible area, and it replaces everything outside with empty space of the right size, so the scrollbar still behaves. When you scroll, rows leaving the window are unmounted and rows entering it are mounted.

FlatList measures that window in units of the visible length of the list. The default windowSize is 21, which means: the visible screen, plus 10 screens above and 10 below. A larger window means fewer blank flashes when you scroll fast, but more memory and more rows to keep alive. A smaller window saves memory but shows blank areas on a fast fling.

The window around the screen

Visible Rows on screen right now.
Above Kept mounted for scrolling back.
Below Pre-rendered before you get there.
Outside Replaced by blank space.

windowSize 21 means 10 screens up, 10 down, plus the visible one.

1 / 2

Stand-in: the virtualization window

The function below computes which rows fall inside the window for a given scroll offset. It uses the same idea as FlatList: the window is windowSize times the viewport height, centered on the viewport.

Which rows stay mounted?

Even with the default window, only a few hundred of the thousand rows exist at any moment, and near the top or bottom the window is clamped. Real FlatList also mounts rows in batches (maxToRenderPerBatch) so a fast scroll does not block the JS thread, and initialNumToRender (default 10) controls how many rows appear on the very first render.

The three biggest wins

1. Stop needless row re-renders

When the parent re-renders (typing in a search field, for example), FlatList re-runs renderItem for rows in its window. If each row is a plain component, every row re-renders even though its data is the same. Wrap the row in React.memo, and keep the props it receives stable:

TSX
import { memo, useCallback } from 'react';
import { FlatList, Pressable, Text } from 'react-native';

const Row = memo(function Row({ item, onSelect }: RowProps) {
  return (
    <Pressable onPress={() => onSelect(item.id)} style={{ padding: 16 }}>
      <Text>{item.title}</Text>
    </Pressable>
  );
});

export function Items({ items }: { items: Item[] }) {
  const onSelect = useCallback((id: string) => {
    console.log('selected', id);
  }, []);

  const renderItem = useCallback(
    ({ item }: { item: Item }) => <Row item={item} onSelect={onSelect} />,
    [onSelect],
  );

  return <FlatList data={items} renderItem={renderItem} keyExtractor={keyOf} />;
}

const keyOf = (item: Item) => item.id;

memo compares props with Object.is. A new inline function or object on every render (onPress={() => ...} created in the parent, style={{...}} built inline) is a new value each time, so memo never skips. Define keyExtractor outside the component or memoize it, use useCallback for handlers you pass to rows, and use StyleSheet.create for styles. (The React Compiler can do much of this automatically, but it is good to understand what it does.)

2. Keep rows cheap

  • Small trees: fewer nested Views means less layout.
  • Avoid expensive work in render: no sorting, filtering or date formatting of the whole list inside a row.
  • Give images a fixed size and a placeholder (see Images, Icons and Media).
  • Keep per-row state tiny, or lift it up.

3. Tell the list the sizes: getItemLayout

Normally FlatList must measure rows after they render, which it cannot do for rows it has not rendered yet, so jumping to row 500 is slow or approximate. If all rows have a fixed height (or you can compute each one), provide getItemLayout:

TSX
const ROW_HEIGHT = 64;

<FlatList
  data={items}
  keyExtractor={keyOf}
  renderItem={renderItem}
  getItemLayout={(_, index) => ({
    length: ROW_HEIGHT,
    offset: ROW_HEIGHT * index,
    index,
  })}
/>

Now the list can compute any row's position instantly: scrollToIndex works without measuring, scrollbar size is exact, and fewer layout passes happen. If the numbers are wrong (rows are not really 64 tall), scrolling will look broken, so only use it for truly fixed sizes. Separators count too: add their height to length and offset.

Props you can tune

Prop What it does Careful
windowSize Size of the mounted window (default 21) Smaller = less memory but blank areas on a fast fling
initialNumToRender Rows drawn on first render (default 10) Enough to fill the screen, no more
maxToRenderPerBatch Rows rendered per batch while scrolling Larger = faster fill, more blocking
removeClippedSubviews Detaches off-screen native views Helps long lists on Android, can cause glitches with some content
getItemLayout Fixed row sizes Must be exact

Change one prop at a time and measure on a real device in a release build; dev mode is much slower and misleads you (see Debugging and Performance Profiling).

Stand-in: how much does memo save?

This stand-in counts row renders. It simulates a list of 50 rows and a parent that re-renders 10 times (like keystrokes in a search box). The memoized version skips a row when none of its props changed according to Object.is, which is what React.memo does. The unstable version passes a new handler each time, so memo cannot help.

Counting row renders: plain, memo, unstable props

Without memo, all 500 row renders happen. With memo but an unstable handler, nothing is saved. With memo and a stable handler, only the first 50 renders happen. This is why "wrapped it in memo and nothing changed" is such a common complaint: the props were never stable.

FlashList

FlatList creates and destroys row views as you scroll. FlashList, a drop-in alternative from Shopify, instead recycles them: a row that scrolls off the top is reused for the row that enters at the bottom, with new data, so far less mounting happens. You install it as a package (@shopify/flash-list) and swap the component:

TSX
import { FlashList } from '@shopify/flash-list';

<FlashList
  data={items}
  renderItem={({ item }) => <Row item={item} />}
  keyExtractor={(item) => item.id}
/>

Older versions also ask for an estimatedItemSize prop (an average row height); check the version you install for which props it expects. Because rows are reused, state stored inside a row (a text input value, an expanded flag) can leak from one item to the next, so keep such state in the data or reset it when the item changes. FlashList is worth trying when profiling shows a long list with complex rows is still slow after memoization; for simple lists the built-in FlatList is enough and has no extra dependency.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does virtualization do in a long list?

    Rows outside the window are not mounted at all, which saves memory and render time.
  2. 2. A row is wrapped in React.memo, but still re-renders on every parent update. What is the most likely cause?

    memo compares props with Object.is. A new function or object each time is never equal, so the row re-renders.
  3. 3. When is getItemLayout appropriate?

    It lets the list compute positions without measuring. Wrong numbers break scrolling, so use it only for exact sizes.
  4. 4. What is the main idea behind FlashList compared with FlatList?

    Recycling reuses a row view for new data, so less mounting happens. Row-local state must therefore be handled carefully.

Summary

  • Virtualization keeps a window of rows mounted; windowSize (default 21) sets how big, trading memory against blank areas on fast scrolls.
  • Memoize rows with React.memo and keep their props stable (useCallback, outside-defined keyExtractor, StyleSheet.create).
  • Keep rows cheap, and provide getItemLayout only for exact, fixed row sizes.
  • Tune one prop at a time and measure in a release build on a real device.
  • Try FlashList when complex rows are still slow; mind state inside recycled rows.

Next, group data and load it page by page in SectionList, Pull to Refresh and Infinite Scroll.