Legend List — Best Practices & Performance Guide

@legendapp/list v2.0+ | React Native 0.72+ | Pure TypeScript — no native dependencies

Critical Rules

1. Always provide keyExtractor with stable, unique IDs. Without it, Legend List cannot track items across data changes, causing unnecessary re-renders and layout bugs.
2. Enable recycleItems={true} for any list beyond a handful of items. This is the single biggest performance win — it reuses view containers instead of creating/destroying them on scroll.
3. Use useRecyclingState instead of useState inside recycled items. Regular useState carries state from the previous item when a container is reused, causing ghost data bugs.
4. Use useRecyclingEffect to reset side effects (animations, subscriptions, timers) when an item container is recycled to a different data item.
5. Provide accurate size estimates via estimatedItemSize or getEstimatedItemSize. Bad estimates cause layout jumping and scroll position inaccuracies.
6. Use getFixedItemSize for any item whose height is known at render time. This skips measurement entirely — the fastest path.
7. Use getItemType when recycleItems is enabled and your list has multiple visually different item types. This ensures containers are only recycled to items with the same structure.
8. Memoize renderItem with useCallback and item components with React.memo. Inline arrow functions create new references every render, triggering unnecessary work.
9. Enable maintainVisibleContentPosition (default in v2) for any list where items are added/removed above the viewport — especially chat and bidirectional lists.
10. Never mutate the data array. Always produce a new array reference with immutable operations ([...prev, newItem], .map(), .filter()).

Code Review & Audit Action