shopify-flash-list
@amazon-devices/shopify__flash-list
provides a fast and performant list component. FlashList
is similar to FlatList
provided by React Native. Props supported by FlatList
are also supported by FlashList
. You can try FlashList
by replacing a FlatList
component and adding a estimatedItemSize
prop. Additionally, FlashList
extends the list of supported props by adding additional props to help achieve optimal performance.
This is a system-deployed library and is available to React Native for Vega apps without a separate installation process. It is deployed as an autolinking library which your app links to at runtime. Compatibility is guaranteed only between the library and the version of React Native for Vega for which it is built.
When you upgrade the version of React Native for Vega upon which your app is built, it is best practice to also upgrade the versions of the libraries that depend on React Native for Vega.
Installation
- Add the JavaScript library dependency in the
package.json
file."dependencies": { ... "@amazon-devices/shopify__flash-list": "~2.0.0" }
- Reinstall dependencies using
npm install
command.
Examples
The examples below use a common dataset and components. Some items have been removed to avoid duplication in examples.
import React from "react";
import { Text, TouchableOpacity } from "react-native";
export const randomColor = () => `#${Math.floor(Math.random() * 16777215).toString(16)}`;
export const DATA = Array.from({ length: 1000 }, (_, i) => ({
title: `Item ${i + 1}`,
bgColor: randomColor(),
height: Math.floor(Math.random() * (140 - 60) + 60),
}))
interface ItemProps {
item: {
bgColor: string;
title: string;
height?: number;
width?: number;
}
}
export const Item = (props: ItemProps) => (
<TouchableOpacity style={{ backgroundColor: props.item.bgColor, flex: 1 }}>
<Text style={{ height: props.item.height, width: props.item.width, fontSize: 20, fontWeight: "500" }}>{props.item.title}</Text>
</TouchableOpacity>
)
FlashList component example
import { FlashList } from "@amazon-devices/shopify__flash-list";
import React from "react";
import { Dimensions, Text, View } from "react-native";
import { DATA, Item } from "./common";
export const App = () => (
<FlashList
data={DATA}
renderItem={({ item }) => <Item item={item} />}
ListHeaderComponent={
<View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ fontSize: 24, fontWeight: "600" }}>FlashList Demo</Text>
</View>
}
estimatedFirstItemOffset={100}
estimatedItemSize={100}
estimatedListSize={{
height: Dimensions.get('screen').height,
width: Dimensions.get('screen').width
}}
/>
)
FlashList with infinite scroll example
import { FlashList } from "@amazon-devices/shopify__flash-list";
import React, { useState } from "react";
import { Dimensions, Text, View } from "react-native";
import { Item } from "./common";
const randomColor = () => `#${Math.floor(Math.random() * 16777215).toString(16)}`;
export const App = () => {
const [data, setData] = useState(Array.from({ length: 20 }, (_, i) => ({
title: `Item ${i + 1}`,
bgColor: randomColor(),
height: Math.floor(Math.random() * (140 - 60) + 60),
})));
const loadMoreData = () => {
const newData = Array.from({ length: 20 }, (_, i) => ({
title: `Item ${data.length + i + 1}`,
bgColor: randomColor(),
height: Math.floor(Math.random() * (140 - 60) + 60),
}))
setData(items => items.concat(newData));
}
return (
<FlashList
data={data}
renderItem={({ item }) => <Item item={item} />}
ListHeaderComponent={
<View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ fontSize: 24, fontWeight: "600" }}>InfiniteScroll Demo</Text>
</View>
}
estimatedFirstItemOffset={100}
estimatedItemSize={100}
estimatedListSize={{
height: Dimensions.get('screen').height,
width: Dimensions.get('screen').width
}}
onEndReached={loadMoreData}
/>
)
}
MasonryFlashList example
MasonryFlashList
is the FlashList
component with many columns.
import { MasonryFlashList } from "@amazon-devices/shopify__flash-list";
import React from "react";
import { Dimensions, Text, View } from "react-native";
import { DATA, Item } from "./common";
export const App = () => (
<MasonryFlashList
data={DATA}
numColumns={3}
renderItem={({ item }) => <Item item={item} />}
estimatedFirstItemOffset={100}
estimatedItemSize={100}
estimatedListSize={{
height: Dimensions.get('screen').height,
width: Dimensions.get('screen').width
}}
ListHeaderComponent={
<View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ fontSize: 24, fontWeight: "600" }}>MasonryList Demo</Text>
</View>
}
/>
);
API reference
Check out the dedicated documentation page for info about this library, API reference and more.
The FlashList
library covers all of the props supported by the FlatList
component. It adds additional props for optimizing performance, as listed below.
Components
Component | Description |
---|---|
FlashList |
React Native FlatList equivalent, with additional props to optimize performance |
AnimatedFlashList |
Adds support for Animated APIs for FlashList |
MasonryFlashList |
FlashList that contains columns, which are also FlashList components |
AutoLayoutView |
Native component used inside FlashList and responsible for recomputing layout |
CellContainer |
Native component that represents a single cell inside the list |
Props
Prop | Description |
---|---|
estimatedItemSize |
A single numeric value that hints FlashList about the approximate size of the items before they're rendered. FlashList can then use this information to decide how many items it needs to draw on the screen before initial load and while scrolling. |
disableAutoLayout |
The FlashList default layout can conflict with custom CellRendererComponent implementations because the layout applies some fixes to child components. You can disable this behavior by setting disableAutoLayout to true . |
disableHorizontalListHeightMeasurement |
FlashList attempts to measure size of horizontal lists by drawing an extra list item in advance. This can sometimes cause issues when used with initialScrollIndex in lists with very little content. You can disable this behavior. |
drawDistance |
Draw distance for advanced rendering. |
estimatedFirstItemOffset |
Specifies how far the first item is drawn from start of the list window or offset of the first item of the list (not the header). Required if you use the initialScrollIndex prop. |
estimatedListSize |
Estimated visible height and width of the list. Not the scroll content size. Defining this prop enables the list to be rendered immediately. Without it, the list first needs to measure its size, leading to a small delay during the first render. |
onBlankArea |
FlashList computes blank space that is visible to the user during scrolling or the initial loading of the list. |
onLoad |
Event raised once the list has drawn items on the screen. It also reports elapsedTimeInMs , which is the time it took to draw the items. |
getItemType |
Allows you to specify item types. Improves recycling if you have different types of items in the list. |
overrideItemLayout |
Used to provide explicit size estimates or change column span of an item. |
overrideProps |
Recommended for debugging only. Internal props of the list override with the provided values. |
FlashList
, as FlatList
, uses ScrollView
under the hood, so it inherits its props.
Implementation details
Not all props supported in React Native FlatList
have an equivalent in FlashList
. See the list below of props in React Native that are not supported by FlashList
.
- Unsupported props
columnWrapperStyle
debug
listKey
onScrollToIndexFailed
windowSize
- Unsupported methods
flashScrollIndicators()
hasMore
getChildContext
getNativeScrollRef()​
getScrollRef
getScrollResponder()
- Props that would bring no value if ported to
FlashList
due to the differences in their underlying implementationdisableVirtualization
getItemLayout
initialNumToRender
maxToRenderPerBatch
recordInteraction
setNativeProps
updateCellsBatchingPeriod
- Props that aren't currently supported on Vega
refreshControl
refreshing
Use of key prop
When migrating from React Native FlatList
to Flashlist
, you should remove any key
props from your item components and their nested components. If you use a key
prop, FlashList
can't recycle views, which removes performance optimizations of Flashlist
.
For example, this code snippet below uses key
props in Text
and View
components.
const MyNestedComponent = ({ item }) => {
return <Text key={item.id}>I am nested!</Text>;
};
const MyItem = ({ item }) => {
return (
<View key={item.id}>
<MyNestedComponent item={item} />
<Text>{item.title}</Text>
</View>
);
};
To optimize Flashlist
, remove the key
props, as shown below.
const MyNestedComponent = ({ item }) => {
return <Text>I am nested!</Text>;
};
const MyItem = ({ item }) => {
return (
<View>
<MyNestedComponent item={item} />
<Text>{item.title}</Text>
</View>
);
};
See the Shopify docs for more details about the key
prop.
Supported versions
Package name | Amazon NPM library version | Vega OS build number | Vega SDK version | Release notes |
---|---|---|---|---|
@amazon-devices/shopify__flash-list |
2.0.1+1.6.3 | OS 1.1 (201010438050) |
0.20 |
Additional resources
For information on additional libraries, see Supported Third-Party Libraries and Services.
Last updated: Sep 30, 2025