1---
2title: Optimize List Performance with Stable Object References
3impact: CRITICAL
4impactDescription: virtualization relies on reference stability
5tags: lists, performance, flatlist, virtualization
6---
7 
8## Optimize List Performance with Stable Object References
9 
10Don't map or filter data before passing to virtualized lists. Virtualization
11relies on object reference stability to know what changed—new references cause
12full re-renders of all visible items. Attempt to prevent frequent renders at the
13list-parent level.
14 
15Where needed, use context selectors within list items.
16 
17**Incorrect (creates new object references on every keystroke):**
18 
19```tsx
20function DomainSearch() {
21  const { keyword, setKeyword } = useKeywordZustandState()
22  const { data: tlds } = useTlds()
23 
24  // Bad: creates new objects on every render, reparenting the entire list on every keystroke
25  const domains = tlds.map((tld) => ({
26    domain: `${keyword}.${tld.name}`,
27    tld: tld.name,
28    price: tld.price,
29  }))
30 
31  return (
32    <>
33      <TextInput value={keyword} onChangeText={setKeyword} />
34      <LegendList
35        data={domains}
36        renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
37      />
38    </>
39  )
40}
41```
42 
43**Correct (stable references, transform inside items):**
44 
45```tsx
46const renderItem = ({ item }) => <DomainItem tld={item} />
47 
48function DomainSearch() {
49  const { data: tlds } = useTlds()
50 
51  return (
52    <LegendList
53      // good: as long as the data is stable, LegendList will not re-render the entire list
54      data={tlds}
55      renderItem={renderItem}
56    />
57  )
58}
59 
60function DomainItem({ tld }: { tld: Tld }) {
61  // good: transform within items, and don't pass the dynamic data as a prop
62  // good: use a selector function from zustand to receive a stable string back
63  const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
64  return <Text>{domain}</Text>
65}
66```
67 
68**Updating parent array reference:**
69 
70Creating a new array instance can be okay, as long as its inner object
71references are stable. For instance, if you sort a list of objects:
72 
73```tsx
74// good: creates a new array instance without mutating the inner objects
75// good: parent array reference is unaffected by typing and updating "keyword"
76const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
77 
78return <LegendList data={sortedTlds} renderItem={renderItem} />
79```
80 
81Even though this creates a new array instance `sortedTlds`, the inner object
82references are stable.
83 
84**With zustand for dynamic data (avoids parent re-renders):**
85 
86```tsx
87const useSearchStore = create<{ keyword: string }>(() => ({ keyword: '' }))
88 
89function DomainSearch() {
90  const { data: tlds } = useTlds()
91 
92  return (
93    <>
94      <SearchInput />
95      <LegendList
96        data={tlds}
97        // if you aren't using React Compiler, wrap renderItem with useCallback
98        renderItem={({ item }) => <DomainItem tld={item} />}
99      />
100    </>
101  )
102}
103 
104function DomainItem({ tld }: { tld: Tld }) {
105  // Select only what you need—component only re-renders when keyword changes
106  const keyword = useSearchStore((s) => s.keyword)
107  const domain = `${keyword}.${tld.name}`
108  return <Text>{domain}</Text>
109}
110```
111 
112Virtualization can now skip items that haven't changed when typing. Only visible
113items (~20) re-render on keystroke, rather than the parent.
114 
115**Deriving state within list items based on parent data (avoids parent
116re-renders):**
117 
118For components where the data is conditional based on the parent state, this
119pattern is even more important. For example, if you are checking if an item is
120favorited, toggling favorites only re-renders one component if the item itself
121is in charge of accessing the state rather than the parent:
122 
123```tsx
124function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
125  const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
126  return <TldFavoriteButton isFavorited={isFavorited} />
127}
128```
129 
130Note: if you're using the React Compiler, you can read React Context values
131directly within list items. Although this is slightly slower than using a
132Zustand selector in most cases, the effect may be negligible.
133