list-performance-function-references — Claude Code rule guide
list-performance-function-references instructs the AI agent to keep object references stable in virtualized lists. It prevents full list re-renders by moving state derivation into child items.
MIT ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settingsWhat list-performance-function-references does
The rule guides coding assistants to avoid calling .map() or .filter() directly before passing arrays into virtualized lists such as LegendList or FlatList. Virtualization mechanisms rely on reference equality to detect changes. Creating brand-new object instances on every parent render forces the list to repaint every visible item.
To keep references steady, the rule prescribes moving transformations and dynamic lookups into item components. It recommends Zustand selectors or context selectors directly inside list item components instead of passing dynamic values down as props. Creating a shallow array copy via toSorted() is acceptable because references to nested objects remain untouched.
Without React Compiler in your setup, omitting useCallback on renderItem breaks list memoization on every keystroke.
What it helps with
- prevent full visible item re-renders during parent state updates
- maintain object reference equality for FlatList and LegendList props
- derive dynamic item state inside child components using selectors
- avoid recreating list datasets on every user keystroke
Example prompts for the agent
- Refactor this search list component to avoid creating new object references
- Apply list-performance-function-references rule to our LegendList implementation
- Move the favorite state lookup inside the list item component
How to install list-performance-function-references
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install react-skills@claude-settings2Manually: put the files in place
.claude/rules/list-performance-function-references.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/list-performance-function-references.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/list-performance-function-references.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/list-performance-function-references.mdManually: put the files in place
.clinerules/list-performance-function-references.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about list-performance-function-references
How to install list-performance-function-references in Claude Code?
Add the repository with /plugin marketplace add fcakyon/claude-codex-settings, then install it using /plugin install react-skills@claude-settings. Alternatively, place the file in .claude/rules/list-performance-function-references.md.
What does list-performance-function-references do?
It directs the AI to maintain reference stability for data passed to virtualized lists and derive dynamic state inside individual item components.
Is sorting allowed before passing data to the list?
Yes, operations like toSorted() produce a new outer array instance while preserving stable inner object references, which works fine.
Source text
list-performance-function-references.md · MIT
---
title: Optimize List Performance with Stable Object References
impact: CRITICAL
impactDescription: virtualization relies on reference stability
tags: lists, performance, flatlist, virtualization
---
## Optimize List Performance with Stable Object References
Don't map or filter data before passing to virtualized lists. Virtualization
relies on object reference stability to know what changed—new references cause
full re-renders of all visible items. Attempt to prevent frequent renders at the
list-parent level.
Where needed, use context selectors within list items.
**Incorrect (creates new object references on every keystroke):**
```tsx
function DomainSearch() {
const { keyword, setKeyword } = useKeywordZustandState()
const { data: tlds } = useTlds()
// Bad: creates new objects on every render, reparenting the entire list on every keystroke
const domains = tlds.map((tld) => ({
domain: `${keyword}.${tld.name}`,
tld: tld.name,
price: tld.price,
}))
return (
<>
<TextInput value={keyword} onChangeText={setKeyword} />
<LegendList
data={domains}
renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
/>
</>
)
}
```
**Correct (stable references, transform inside items):**
```tsx
const renderItem = ({ item }) => <DomainItem tld={item} />
function DomainSearch() {
const { data: tlds } = useTlds()
return (
<LegendList
// good: as long as the data is stable, LegendList will not re-render the entire list
data={tlds}
renderItem={renderItem}
/>
)
}
function DomainItem({ tld }: { tld: Tld }) {
// good: transform within items, and don't pass the dynamic data as a prop
// good: use a selector function from zustand to receive a stable string back
const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
return <Text>{domain}</Text>
}
```
**Updating parent array reference:**
Creating a new array instance can be okay, as long as its inner object
references are stable. For instance, if you sort a list of objects:
```tsx
// good: creates a new array instance without mutating the inner objects
// good: parent array reference is unaffected by typing and updating "keyword"
const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
return <LegendList data={sortedTlds} renderItem={renderItem} />
```
Even though this creates a new array instance `sortedTlds`, the inner object
references are stable.
**With zustand for dynamic data (avoids parent re-renders):**
```tsx
const useSearchStore = create<{ keyword: string }>(() => ({ keyword: '' }))
function DomainSearch() {
const { data: tlds } = useTlds()
return (
<>
<SearchInput />
<LegendList
data={tlds}
// if you aren't using React Compiler, wrap renderItem with useCallback
renderItem={({ item }) => <DomainItem tld={item} />}
/>
</>
)
}
function DomainItem({ tld }: { tld: Tld }) {
// Select only what you need—component only re-renders when keyword changes
const keyword = useSearchStore((s) => s.keyword)
const domain = `${keyword}.${tld.name}`
return <Text>{domain}</Text>
}
```
Virtualization can now skip items that haven't changed when typing. Only visible
items (~20) re-render on keystroke, rather than the parent.
**Deriving state within list items based on parent data (avoids parent
re-renders):**
For components where the data is conditional based on the parent state, this
pattern is even more important. For example, if you are checking if an item is
favorited, toggling favorites only re-renders one component if the item itself
is in charge of accessing the state rather than the parent:
```tsx
function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
return <TldFavoriteButton isFavorited={isFavorited} />
}
```
Note: if you're using the React Compiler, you can read React Context values
directly within list items. Although this is slightly slower than using a
Zustand selector in most cases, the effect may be negligible.
© fcakyon · MIT · fcakyon/claude-codex-settings