Cursor rule

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