Overview

LLM links: llms.txt, llms-full.txt, llms-full.md

Legend List is a high-performance virtualized list for React Native and React DOM. It is a drop-in replacement for FlatList/FlashList on React Native, and a DOM-native virtual list for React.

✨ Dynamic sizes with no manual measuring
✨ Accurate initialScrollIndex and initialScrollAtEnd
✨ Chat and AI chat without inverted lists or crazy hacks
✨ Bidirectional infinite lists with scroll anchoring
✨ Floating composer and overlay inset support
✨ Optional item recycling with recycling-aware hooks
🧲 Sticky headers, SectionList, and always-mounted rows
🌐 React Native and DOM-native React support

For more information, check out:

It's fast

This video was recorded as a performance test scrolling ludicrously fast with heavy items. LegendList handles expensive components with a quick recovery.

It uses less resources

A FlashLight measurement of the above test shows that LegendList uses less CPU while scrolling. And it uses less memory too! See the FlashLight results for more details.

Built for Chat and Feeds

Legend List has first-class primitives for timelines that grow at both ends:

initialScrollAtEnd starts at the newest item without rendering the whole history first.
initialScrollIndex supports target indices with viewOffset and viewPosition.
maintainScrollAtEnd follows new messages while the user is already near the end.
maintainVisibleContentPosition keeps the current viewport stable during prepends and size changes.
anchoredEndSpace reserves tail space so a newly sent row can land in a readable position above overlays.
onStartReached and onEndReached support bidirectional pagination.

See Guides and Keyboard & Animated.

Choose your platform

React Native → import from @legendapp/list/react-native and start with Getting Started (React Native).
React (Web) → import from @legendapp/list/react and start with Getting Started (Web).
React Native Web → use the React Native entrypoint so your app keeps React Native component semantics.

All of these imports run the same JS engine, the separate import paths are just for platform-specific types.

Advanced List Features

Legend List v3 also includes:

SectionList from @legendapp/list/section-list, with sticky section headers and scrollToLocation
stickyHeaderIndices with stickyHeaderConfig
alwaysRender for keeping top, bottom, explicit index, or key-based rows mounted
numColumns and overrideItemLayout for grid-style lists with spanning items
dataVersion and itemsAreEqual for mutable data or semantic equality checks
viewabilityConfig, viewabilityConfigCallbackPairs, useViewability, and useViewabilityAmount
async imperative ref methods like scrollToIndex, scrollToEnd, and scrollToOffset
getState(), listener helpers, scroll metrics, and clearCaches for advanced integrations

What’s new in v3

Web support (no React Native dependency required)
Improved performance and stability
initialScrollAtEnd, improved initial-scroll targeting, and async imperative scroll methods
anchoredEndSpace and contentInsetEndAdjustment for chat, AI chat, floating composers, and overlay UI
KeyboardAwareLegendList, useKeyboardChatComposerInset, and useKeyboardScrollToEnd
SectionList component (@legendapp/list/section-list)
alwaysRender for keeping selected items mounted
stickyHeaderIndices and stickyHeaderConfig
useWindowScroll for document-level web scrolling
Reanimated sharedValues and itemLayoutAnimation props
estimatedHeaderSize, dataVersion, and itemsAreEqual
Expanded getState() with listener helpers, getAverageItemSizes(), and scroll metrics

Read the full change summary in Migration to v3.