Skip to main content

​
Requirements

FlashList v2 is designed exclusively for React Native’s new architecture. It will not run on the old architecture.
Before installing FlashList, ensure your project meets these requirements:
  • React Native with new architecture enabled
  • React Native 0.68 or higher recommended
  • TypeScript support (optional but recommended)

​
Install the Package

Add FlashList to your project using your preferred package manager: 
npm install @shopify/flash-list

​
Peer Dependencies

FlashList requires the following peer dependencies (which are typically already in your React Native project):
  • react
  • react-native
  • @babel/runtime
These are usually already installed in React Native projects. If not, install them: 
npm install react react-native @babel/runtime

​
Verify Installation

After installation, verify that FlashList is working correctly by importing it in your code: 
import { FlashList } from "@shopify/flash-list";
If you see an error about the new architecture, make sure you’ve enabled it in your React Native project. FlashList v2 will throw a runtime error if the new architecture is not enabled.

​
Platform-Specific Setup

​
iOS

For iOS projects, install pods after adding the package: 
cd ios && pod install && cd ..

​
Android

No additional setup required for Android. The package will be automatically linked.

​
Web (React Native Web)

FlashList v2 works with React Native Web out of the box. No additional configuration needed.

​
TypeScript Support

FlashList includes comprehensive TypeScript definitions. No additional @types package is needed. The package exports all necessary types: 
import {
  FlashList,
  FlashListProps,
  ListRenderItem,
  ListRenderItemInfo,
  FlashListRef,
} from "@shopify/flash-list";

​
Troubleshooting

​
Error: “FlashList v2 only supports new architecture”

This error means you’re trying to use FlashList v2 on a project without the new architecture enabled. Solutions:
  1. Enable the new architecture in your React Native project
  2. Or use FlashList v1.x for old architecture support

​
Metro bundler issues

If you encounter bundler issues, try: 
# Clear Metro bundler cache
npx react-native start --reset-cache

# Or for Expo
npx expo start -c

​
Build errors on iOS

If you get build errors on iOS: 
cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

​
Next Steps

Quick Start

Learn how to use FlashList with a hands-on tutorial

Build docs developers (and LLMs) love

Get started for freeTalk to us