FlatList and Virtualization

"The list is the origin of culture." — Umberto Eco, The Infinity of Lists (2009)

Almost every screen in almost every app is a list, and almost everything anybody knows about FlatList is a slogan: it only renders what is on screen.

It does not. I measured it. With the default configuration, a list showing ten rows has around two hundred and eleven of them rendered — a hundred above the viewport, ten in it, a hundred below. That is not a bug or a leak; it is precisely what the constants in the source ask for, and it is the difference between a list that scrolls smoothly and one that shows blank space every time you flick.

Virtualization is not about rendering less. It is about rendering a bounded amount regardless of how much data there is, and about choosing where that bound sits — which turns out to be a decision with four numbers in it, all of which have defaults, and none of which mean what their names suggest until you read the arithmetic.

Virtualization is not "render what is visible"

Start with the constants, because they are stated plainly in one file and almost never quoted.

VirtualizedListProps.js defines a helper per prop, each of which is one line:

Two of those units are the whole chapter. windowSize and the reached-thresholds are measured in viewports, not rows and not pixels, which is why tuning them by intuition goes wrong: windowSize: 2 sounds conservative and is in fact drastic, and onEndReachedThreshold: 0.5 is half a screen rather than half a list.

The window is twenty-one screens

The arithmetic is in computeWindowedRenderLimits, and the four lines that matter are these:

const visibleBegin = Math.max(0, offset);
const visibleEnd = visibleBegin + visibleLength;
const overscanLength = (windowSize - 1) * visibleLength;

const leadFactor = 0.5; // Math.max(0, Math.min(1, velocity / 25 + 0.5));

const overscanBegin = Math.max(0, visibleBegin - (1 - leadFactor) * overscanLength);
const overscanEnd = Math.max(0, visibleEnd + leadFactor * overscanLength);

overscanLength is twenty viewports. leadFactor splits it evenly, ten each way. And the commented-out expression beside leadFactor is an artefact worth noticing: the list used to bias the window in the direction of travel, based on velocity, and the comment two lines above says why it stopped — "Considering velocity seems to introduce more churn than it's worth."

Run it and the numbers stop being abstract:

That table is the argument against tuning windowSize downward as a reflex. Going from 21 to 5 cuts the mounted rows by three quarters, which is a real memory saving on a heavy row — and it also cuts the slack from ten screens of runway to two, which a fast flick will outrun.

Here is the same measurement in the playground, against the real implementation. React Native Web vendors React Native's own VirtualizedList — the defaults in its copy are the identical 10, 10 and 21 — so this is the real algorithm running in your browser, not an approximation of it.

The two things to watch are that the count is much larger than the visible rows, and that it is bounded: scrolling to row 900 does not mount 900 components. Bounded, not minimal, is the property virtualization actually provides.

It gets there ten cells at a time

Rendering two hundred components in one frame would itself be a stall, so the list does not. The rest of computeWindowedRenderLimits starts from the visible range and expands outward one cell at a time, stopping when it has added maxToRenderPerBatch new cells, and picking up again after updateCellsBatchingPeriod milliseconds.

The loop is stopped early in the real implementation when the list is scrolling, so the work happens in the gaps rather than competing with the scroll. The shape to hold is that initialNumToRender governs the first paint, maxToRenderPerBatch and updateCellsBatchingPeriod govern how fast the runway is built, and windowSize governs how long the runway is.

What the list has to measure, and what you can tell it

A windowed list needs to know where every row is, and by default it does not — it discovers each row's height from onLayout as that row mounts, and approximates the rest from what it has seen. That works, and it costs two things: the approximation is wrong until enough rows have been measured, so scrollToIndex on an unmeasured row is unreliable; and every mount does layout work that could have been arithmetic.

getItemLayout is how you skip all of it, and it is worth it whenever rows are a known height:

getItemLayout={(data, index) => ({ length: ROW_HEIGHT, offset: ROW_HEIGHT * index, index })}

The other thing the list needs is identity, and the default is a trap worth knowing. FlatList's built-in key extractor is six lines:

export function keyExtractor(item: any, index: number): string {
  if (typeof item === 'object' && item?.key != null) return item.key;
  if (typeof item === 'object' && item?.id != null) return item.id;
  return String(index);
}

An object with a key or an id is handled. Everything else falls back to the array index, silently, which is correct for a list that never changes and wrong the moment one does.

Tick the first row of each list and reverse. In the index-keyed list the tick stays in position one and is now attached to a different person; in the id-keyed list it follows the person. Neither list errors, and only one of them is right.

This matters more in a virtualized list than in a plain map, because rows mount and unmount constantly as the window moves — so a mismatched key does not merely misplace state on reorder, it can attach a row's state to whatever scrolls into its position.

Tuning, and when not to

The four numbers are adjustable and the honest advice is to leave them alone until you have measured something.

Raise initialNumToRender only if the first screen is visibly short — it delays first paint, which is the most expensive moment in the list's life. Lower windowSize when rows are genuinely heavy and memory is the constraint you measured, accepting more blank space on fast scrolls; raise it when users flick hard through light rows. Raise maxToRenderPerBatch to fill the runway faster at the cost of larger chunks of work per pass. And set removeClippedSubviews knowing it is a native-side optimisation with platform-specific quirks rather than a free win.

The two changes that are almost always worth making are not tuning at all: supply getItemLayout when rows are a fixed height, and supply a keyExtractor that returns a stable identity. Both remove work rather than rebalancing it.

Common Mistakes

1. Believing the list renders only what is visible. At the defaults it renders about twenty-one viewports' worth.
2. Reading windowSize as a row count. It is measured in viewports, so 21 is twenty-one screenfuls.
3. Setting windowSize: 1 to "optimise". That renders only the visible rows and guarantees blank space on every flick.
4. Reading onEndReachedThreshold as rows or a percentage. It is also in viewports; 2 means two screen-heights of runway.
5. Doing real work in renderItem. Whatever it costs, it costs two hundred times, not ten.
6. Relying on the default key extractor. Without a key or id on the item it falls back to the array index, silently.
7. Keying by index in a list that reorders. State attaches to positions rather than to items, with no error.
8. Omitting getItemLayout for fixed-height rows. The list then measures every row it mounts and guesses the rest.
9. Expecting scrollToIndex to be exact on unmeasured rows. Without getItemLayout the offsets are approximations.
10. Tuning the four numbers before measuring. They trade against each other, and the defaults are a considered position.

Interview Corner

Hands-on

Summary

• Virtualization renders a bounded amount, not a minimal one. At the defaults a list showing ten rows has about 211 mounted.
• windowSize is measured in viewports, so its default of 21 means ten screenfuls above, one visible, ten below.
• onEndReachedThreshold uses the same unit — 2 is two screen-heights of runway, not two rows.
• overscanLength is (windowSize - 1) * visibleLength, split evenly by a hard-coded leadFactor of 0.5.
• The velocity-biased window was tried and removed, and the dead expression is still there beside the constant that replaced it.
• The window is filled incrementally, maxToRenderPerBatch new cells per pass every updateCellsBatchingPeriod milliseconds.
• initialNumToRender governs first paint, which is the most expensive moment in the list's life.
• Anything expensive in renderItem costs two hundred times, not ten — fix the row before tuning the list.
• The default key extractor falls back to the array index when an item has no key or id, silently.
• React Native windows rather than recycles, because a declarative renderer has no pool to dequeue from.

In the next chapter, Keys, Memoisation and Re-renders, we stay inside the row: why a re-render that is free on a laptop is visible on a phone, what React.memo actually compares, and how a single inline arrow in a parent can defeat every optimisation below it.