shopify-flash-list - Amazon Vega Docs

The @amazon-devices/shopify__flash-list library 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 library is system-deployed and available to React Native for Vega apps without a separate installation process. The library is autolinking, which your app links to at runtime. The library is guaranteed to be compatible only with the version of React Native for Vega for which it’s built. When you uplevel your app’s version of React Native for Vega, consider the best practice of upleveling its library dependencies.

Installation

Add the JavaScript library dependency in the package.json file.

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

Reinstall dependencies using the npm install command.

Examples

The following examples 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

See the documentation page for information about this library and API reference. 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`	The 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. Reports `elapsedTimeInMs`, which is the time it took to draw the items.
`getItemType`	Specifies item types. Improves recycling if you have different types of items in the list.
`overrideItemLayout`	Provides explicit size estimates or you can 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.

Known issues and limitations

Not all props supported in React Native FlatList have an equivalent in FlashList. The following props in React Native aren’t 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

ItemSeparatorComponent known issue

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

Use of the `key` prop

If you use a key prop, FlashList can’t recycle views, which removes performance optimizations of Flashlist. Therefore, when migrating from React Native FlatList to Flashlist, you should remove any key props from your item components and their nested components. 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.

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

Supported Third-Party Libraries and Services.

​Installation

​Examples

​FlashList component example

​FlashList with infinite scroll example

​MasonryFlashList example

​API reference

​Components

​Props

​Known issues and limitations

​ItemSeparatorComponent known issue

​Use of the key prop

​Supported versions

​Related topics