Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settings
Open on GitHub

What 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-settings

2Manually: put the files in place

.claude/rules/list-performance-function-references.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set113

The whole set →
review-overleaf review-overleaf — a skill for Claude Code and Codex that pulls unresolved reviewer comments from an Overleaf project, locates each in your local LaTeX repository, and proposes edits. CX Codex +1 ★ 1,216repo stars setup setup — a skill for Claude Code and Codex that configures and refreshes Overleaf session tokens for overleaf-skills. Runs when requests return 401 unauthorized or expired sessions. CX Codex +1 ★ 1,216repo stars update-readme update-readme — a command for Claude Code and Codex rebuilds the plugin sections in README.md. It reads the plugin folders and marketplace data. CX Codex +1 ★ 1,216repo stars openship-deploy openship-deploy — a skill for running and maintaining a self-hosted OpenShip instance from the CLI: app deploys, domains, backups, upgrades. CX Codex +1 ★ 1,216repo stars server-hoist-static-io The server-hoist-static-io rule for Claude Code and Codex moves static asset I/O to module scope, loading files once instead of on every server-function request. CX Codex +1 ★ 1,216repo stars slides slides assembles PowerPoint decks with PptxGenJS, layout helpers, PNG rendering, and overflow detection for slide content. CX Codex +1 ★ 1,216repo stars ui-menus ui-menus — a rule for Claude Code and Codex that switches menu generation from custom JS components to native platform elements via zeego. Triggered when creating dropdowns or context menus. CX Codex +1 ★ 1,216repo stars schema A skill for Claude Code and Codex reviews and fixes JSON-LD structured data. It helps choose schema types and trace why a page is not getting a rich result. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open