shopify-flash-list - Amazon Vega Docs

@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. Select the tab for your React Native version.

React Native 0.72
React Native 0.83

"dependencies": {
...
"@amazon-devices/shopify__flash-list": "~2.0.0"
}

"dependencies": {
...
"@amazon-devices/shopify__flash-list": "~2.0.9000000000"
}

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 implementation
- disableVirtualization
- getItemLayout
- initialNumToRender
- maxToRenderPerBatch
- recordInteraction
- setNativeProps
- updateCellsBatchingPeriod
Props that aren’t currently supported on Vega
- refreshControl
- refreshing

ItemItemSeparatorComponent known issue When using the ItemItemSeparatorComponent, you may experience issues with the JS Thread when scrolling based on Perfetto traces.

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

NPM package version	Vega SDK version	Vega OS version	React Native version
~2.0.0	0.23 and earlier	`OS 1.1 (1401010009820)` and earlier	0.72
~2.0.9000000000	0.24	`OS 1.2 (2101020054720)`	0.83

Additional resources

For information on additional libraries, see Supported Third-Party Libraries and Services.

​Installation

​Examples

​FlashList component example

​FlashList with infinite scroll example

​MasonryFlashList example

​API reference

​Components

​Props

​Implementation details

​Use of key prop

​Supported versions

​Additional resources