Getting Started

Legend List is a high performance virtualized ScrollView library for React Native. Compared to FlatList and FlashList it's faster, simpler, and has useful features they don't support.

  • ✨ Extremely fast
  • ✨ Dynamic item sizes
  • ✨ Optional recycling
  • ✨ Bidirectional infinite lists
  • ✨ Chat list without inverting
  • ✨ Maintain content view position
  • ✨ Recycling hooks

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.

Install

npm install @legendapp/list

Usage

Legend List is a virtualized ScrollView component for React Native with optional recycling, that can massively increase performance of rendering long lists. Rather than rendering every item in the list, it only renders the items that are in view, which significantly reduces the amount of items that need to render.

Legend List is a drop-in replacement for FlatList or FlashList. So since you're likely coming from one of those, we'll start with a guide on how to switch.

Quick Start

import { Text } from "react-native";
import { LegendList } from "@legendapp/list";

const items = [
  { id: "1", title: "Item 1" },
  { id: "2", title: "Item 2" },
  { id: "3", title: "Item 3" },
];

export function MyList() {
  return (
    <LegendList
      data={items}
      renderItem={({ item }) => <Text>{item.title}</Text>}
      keyExtractor={(item) => item.id}
      recycleItems
    />
  );
}

Switch from FlashList

If you're coming from FlashList, in most cases you can just rename the component and it will work as expected. But note that Legend List does not recycle items by default, so to match FlashList's behavior you can enable recycleItems. See Recycling Items for more details of recycling behavior.

return (
-  <FlashList
+  <LegendList
      data={items}
      renderItem={({ item }) => <Text>{item.title}</Text>}
+     recycleItems
  />
)

Switch from FlatList

If you're coming from FlatList, Legend List should immediately be much faster. But you may want to add the recycleItems prop to add extra performance.

return (
-  <FlatList
+  <LegendList
      data={items}
      renderItem={({ item }) => <Text>{item.title}</Text>}
+     recycleItems
  />
)

See Props for all properties of LegendList.

Supported Platforms

  • Android
  • iOS
  • React Native Web
  • React Native MacOS
  • React Native Windows
  • TV platforms
  • Any React Native platform should work since there's no native code, but if not please let us know!

Community

Join us on Discord or Github to get involved with the Legend community.

Talk to Jay on Bluesky or Twitter.

Contributing

We welcome contributions! Please read our Contributing Guide on Github. And we welcome documentation PRs in our documentation repo.

Legend Kit

Legend Kit is our early but growing collection of high performance headless components, general purpose observables, transformer computeds, React hooks that don't re-render, and observable tools for popular frameworks. Check out Legend Kit to learn more.

Props

Next Page