# Getting Started

Getting Started — Legend List documentation.

Source: https://legend.so/list/v2/getting-started/

Legend List v2 documentation. **Archived version.** [Read the current documentation.](https://legend.so/list/v3/overview/)

LLM links: [llms.txt](https://legend.so/list/v2/llms.txt), [llms-full.txt](https://legend.so/list/v2/llms-full.txt), [llms-full.md](https://legend.so/list/v2/llms-full.md)

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:

-   [Legend List: Optimizing for Mobile & Web | React Universe Conf 2025](https://www.youtube.com/watch?v=Ui3qVl80Pzg)
-   [Legend List: Optimizing for Peak List Performance | App.js Conf 2025](https://www.youtube.com/watch?v=4nfxSE9OByQ)
-   [Jay's conversation on React Native Radio](https://infinite.red/react-native-radio/rnr-325-legend-list-with-jay-meistrich)

## [It's fast!](https://legend.so/list/v2/getting-started/#its-fast)

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

[Video](https://legend.so/assets/legendlist2.mp4)

  

## [It uses less resources](https://legend.so/list/v2/getting-started/#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](https://legend.so/list/flashlight.html) for more details.

![](https://legend.so/list/flashlight.png)

## [Install](https://legend.so/list/v2/getting-started/#install)

```bash
npm install @legendapp/list@2
```

## [Usage](https://legend.so/list/v2/getting-started/#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](https://legend.so/list/v2/getting-started/#quick-start)

```jsx
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](https://legend.so/list/v2/getting-started/#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](https://legend.so/list/v2/performance#recycling-list-items) for more details of recycling behavior.

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

### [Switch from FlatList](https://legend.so/list/v2/getting-started/#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.

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

See [Props](https://legend.so/list/v2/props) for all properties of LegendList.

## [Supported Platforms](https://legend.so/list/v2/getting-started/#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](https://legend.so/list/v2/getting-started/#community)

Join us on [Discord](https://discord.gg/5CBaNtADNX) or [Github](https://github.com/LegendApp/legend-list) to get involved with the Legend community.

Talk to Jay on [Bluesky](https://bsky.app/profile/jayz.us) or [Twitter](https://twitter.com/jmeistrich).

## [Contributing](https://legend.so/list/v2/getting-started/#contributing)

We welcome contributions! Please read our [Contributing Guide](https://github.com/LegendApp/legend-list) on Github. And we welcome documentation PRs in our [documentation repo](https://github.com/LegendApp/legend-docs).

## [Legend Kit](https://legend.so/list/v2/getting-started/#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](https://www.legendapp.com/kit) to learn more.

[View Markdown](https://legend.so/list/v2/getting-started.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Getting+Started&body=Page%3A+https%3A%2F%2Flegend.so%2Flist%2Fv2%2Fgetting-started%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)