LegendApp/legend-list

A high-performance list component for React Native

Summary

LegendList is a high-performance list component for React Native (and React) written in TypeScript with no native dependencies. It is designed as a drop-in replacement for FlatList and FlashList, with an emphasis on handling dynamically sized items. The package is MIT-licensed and the project aims to keep the bundle small.

What it is useful for

Engineers rendering long, variable-height lists in React Native — social feeds, activity logs, product catalogs, or chat screens — are the target users. Standard FlatList is well known to struggle when row heights vary, and LegendList is built to handle that case natively without extra configuration.

Chat interfaces get specific attention in the README. With alignItemsAtEnd and maintainScrollAtEnd, messages can be aligned to the bottom of the view without using an inverted list, sidestepping the animation glitches that inverted lists tend to introduce. The library also documents bidirectional infinite scrolling with no flashes or scroll jumping, which is useful for timelines that grow in both directions.

On the web, the scrollElement prop lets the list share an ancestor element's scrollbar, supporting layouts with sticky headers or multiple list columns where you want a single scrollable container.

How engineers can use it

Install with the package manager of your choice:

• bun add @legendapp/list
• npm install @legendapp/list
• yarn add @legendapp/list

Then import from the platform-specific entry point:

• React Native: import { LegendList } from "@legendapp/list/react-native"
• React (DOM): import { LegendList } from "@legendapp/list/react"

The README's example defines a UserData interface (id, name, photoUri) and renders rows via renderItem, using keyExtractor for stable keys. The recommended performance flags are recycleItems={true} and maintainVisibleContentPosition. A ref typed as LegendListRef exposes imperative methods like scrollTo.

A few caveats worth knowing. recycleItems reuses item component instances, which can cause surprising state retention if your rows hold local state; the README recommends leaving it off if items have complex internal state. The roadmap lists several features as not yet implemented: column spans, overrideItemLayout, sticky headers, masonry layout, and getItemType. The README points readers to the full documentation site for anything beyond what is shown in the example.

To run the example app locally, the documented steps are cd example, bun i, then bun run ios.