Flash List

https://shopify.github.io/flash-list/docs
Admin
Flash List is a fast and performant React Native list component that eliminates blank cells and can...
Tokens:22,778
Snippets:283
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Manual Benchmark Example

Source: https://shopify.github.io/flash-list/docs/guides/list-profiling

An example demonstrating a complete manual benchmark setup for a FlashList. It includes data generation, state management for results, and UI elements to trigger and display benchmark status.

```typescript
const generateData = (count: number): DataItem[] => {
  return Array.from({ length: count }, (_, index) => ({
    id: `item-${index}`,
    title: `Item ${index}`,
    value: Math.floor(Math.random() * 100),
  }));
};

const ManualBenchmarkExample = () => {
  const flashListRef = useRef<FlashListRef<DataItem>>(null);
  const [data] = useState(() => generateData(500));
  const [benchmarkResult, setBenchmarkResult] = useState<string>("");

  const { startBenchmark, isBenchmarkRunning } = useBenchmark(
    flashListRef,
    (result) => {
      if (!result.interrupted) {
        setBenchmarkResult(result.formattedString || "No results");
        Alert.alert("Benchmark Complete", result.formattedString);
      }
    },
    {
      startManually: true,
      repeatCount: 3,
      speedMultiplier: 1.5,
    }
  );

  const renderItem = ({ item }: { item: DataItem }) => (
    <View style={styles.item}>
      <Text style={styles.title}>{item.title}</Text>
      <Text style={styles.value}>Value: {item.value}</Text>
    </View>
  );

  return (
    <View style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.headerText}>Manual Benchmark Example</Text>
        <Button
          title={isBenchmarkRunning ? "Running..." : "Start Benchmark"}
          onPress={startBenchmark}
          disabled={isBenchmarkRunning}
        />
      </View>

      <FlashList
        ref={flashListRef}
        data={data}
        renderItem={renderItem}
        keyExtractor={(item) => item.id}
      />

      {benchmarkResult ? (
        <View style={styles.resultContainer}>
          <Text style={styles.resultText}>{benchmarkResult}</Text>
        </View>
      ) : null}
    </View>
  );
};

```

--------------------------------

### Example: Masonry Layout

Source: https://shopify.github.io/flash-list/docs/usage

This example shows how to implement a masonry layout with `masonry` and `numColumns`.

```jsx
<FlashList
  data={data}
  masonry
  numColumns={3}
  renderItem={({ item }) => <MasonryItem item={item} />}
/>
```

--------------------------------

### Example: Maintain Visible Content Position for Chat

Source: https://shopify.github.io/flash-list/docs/usage

This example demonstrates using `maintainVisibleContentPosition` with `autoscrollToBottomThreshold` and `startRenderingFromBottom` for a chat interface.

```jsx
<FlashList
  data={chatMessages}
  maintainVisibleContentPosition={{
    autoscrollToBottomThreshold: 0.2,
    startRenderingFromBottom: true,
  }}
  renderItem={({ item }) => <ChatMessage message={item} />}
/>
```

--------------------------------

### Install FlashList with Expo

Source: https://shopify.github.io/flash-list/docs

Install FlashList and expo-dev-client for Expo projects, especially when using development builds. This command ensures compatibility with Expo's ecosystem.

```bash
npx expo install @shopify/flash-list expo-dev-client  

```

--------------------------------

### Basic renderItem Usage Example

Source: https://shopify.github.io/flash-list/docs/usage

An example of how to implement and use the `renderItem` prop to display item titles. Ensure your data items have a `title` property and a unique `key`.

```typescript
renderItem = ({item}) => (
  <Text>{item.title}</Text>
);
...
<FlashList data={[{title: 'Title Text', key: 'item1'}]} renderItem={renderItem} />

```

--------------------------------

### Example: Render and Test FlashList Component

Source: https://shopify.github.io/flash-list/docs/testing

This example demonstrates how to render a FlashList component using @testing-library/react-native and assert the presence of an item by its text content. This is useful for verifying that your list renders correctly.

```javascript
import React from "react";  
import { render } from "@testing-library/react-native";  
  
describe("MyFlashListComponent", () => {  
  it("renders items", () => {  
    const { getByText } = render(<MyFlashListComponent />);  
    const element = getByText("Title of one of the items");  
    // Do something with element ...  
  });  
});  
```

--------------------------------

### Install FlashList with Yarn

Source: https://shopify.github.io/flash-list/docs

Add the FlashList package to your project using Yarn. This is the primary installation command for most React Native projects.

```bash
yarn add @shopify/flash-list  

```

--------------------------------

### Install FlashList v2

Source: https://shopify.github.io/flash-list/docs/v2-migration

Update your project to use FlashList version 2.0.0 or later using npm or yarn.

```bash
npm install @shopify/flash-list@^2.0.0  
# or  
yarn add @shopify/flash-list@^2.0.0  
```

--------------------------------

### Complete FlashList Example with Sticky Headers

Source: https://shopify.github.io/flash-list/docs/guides/section-list

Presents the full implementation of a contacts list using FlashList, including data transformation, item rendering, type identification, and sticky header configuration.

```typescript
import React from "react";  
import { StyleSheet, Text } from "react-native";  
import { FlashList } from "@shopify/flash-list";  
  
interface Contact {  
  firstName: string;  
  lastName: string;  
}  
  
const contacts: (string | Contact)[] = [  
  "A",  
  { firstName: "John", lastName: "Aaron" },  
  "D",  
  { firstName: "John", lastName: "Doe" },  
  { firstName: "Mary", lastName: "Dianne" },  
];  
  
const stickyHeaderIndices = contacts  
  .map((item, index) => {  
    if (typeof item === "string") {  
      return index;  
    } else {  
      return null;  
    }  
  })  
  .filter((item) => item !== null) as number[];  
  
const ContactsFlashList = () => {  
  return (  
    <FlashList  
      data={contacts}  
      renderItem={({ item }) => {  
        if (typeof item === "string") {  
          // Rendering header  
          return <Text style={styles.header}>{item}</Text>;  
        } else {  
          // Render item  
          return <Text>{item.firstName}</Text>;  
        }  
      }}  
      stickyHeaderIndices={stickyHeaderIndices}  
      getItemType={(item) => {  
        // To achieve better performance, specify the type based on the item  
        return typeof item === "string" ? "sectionHeader" : "row";  
      }}  
    />  
  );
};

const styles = StyleSheet.create({
  header: {
    fontSize: 32,
    backgroundColor: "#fff",
  },
});  

```

--------------------------------

### Initial Scroll Index Prop

Source: https://shopify.github.io/flash-list/docs/usage

Specify the `initialScrollIndex` prop to start rendering from a specific item.

```typescript
initialScrollIndex?: number;
```

--------------------------------

### Setup Jest for FlashList Measurements

Source: https://shopify.github.io/flash-list/docs/testing

Add this line to your jest-setup.js file to mock FlashList measurements and prevent all items from mounting during tests. Ensure your jest.config.js includes the correct preset and setupFiles.

```javascript
require("@shopify/flash-list/jestSetup");  
```

--------------------------------

### Original Item Component with `key` prop (Illustrative)

Source: https://shopify.github.io/flash-list/docs/fundamentals/performance

This example demonstrates the incorrect usage of the `key` prop within item and nested components, which hinders FlashList's view recycling and degrades performance. It is provided for contrast to the recommended approach.

```javascript
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>
  );
};

```

--------------------------------

### FlashList with onChangeStickyIndex Callback

Source: https://shopify.github.io/flash-list/docs/usage

Implement a callback to detect changes in the currently displayed sticky header. This example logs the previous and current sticky header indices to the console.

```javascript
<FlashList  
  data={sectionData}  
  stickyHeaderIndices={[0, 10, 20]}  
  onChangeStickyIndex={(current, previous) => {  
    console.log(`Sticky header changed from ${previous} to ${current}`);  
  }}  
  renderItem={({ item }) => <ListItem item={item} />}
/>  

```

--------------------------------

### onBlankArea

Source: https://shopify.github.io/flash-list/docs/usage

Callback triggered when blank space is visible to the user during scrolling or initial loading. Reports visible blank space at the start and end of the screen.

```APIDOC
## onBlankArea

### Description
Callback triggered when blank space is visible to the user during scrolling or initial loading. Reports visible blank space at the start and end of the screen.

### Signature
`(blankAreaEvent: { offsetStart: number; offsetEnd: number; blankArea: number; }) => void`

### Parameters
- **blankAreaEvent** (object) - Event object containing blank area information.
  - **offsetStart** (number) - Visible blank space on top of the screen (while going up).
  - **offsetEnd** (number) - Visible blank space at the end of the screen (while going down).
  - **blankArea** (number) - Maximum of `offsetStart` and `offsetEnd`.

### Notes
- This callback will be triggered even if the blanks are excepted - for example, when the list does not have enough items to fill the screen.
- This event isn't synced with `onScroll` event from the JS layer but works with native methods `onDraw` (Android) and `layoutSubviews` (iOS).
```

--------------------------------

### SectionList Example

Source: https://shopify.github.io/flash-list/docs/guides/section-list

Demonstrates a typical implementation of a contacts list using React Native's SectionList component.

```typescript
import React from "react";  
import { SectionList, StyleSheet, Text } from "react-native";  
  
interface Contact {  
  firstName: string;  
  lastName: string;  
}  
  
interface Section {  
  title: string;  
  data: Contact[];  
}  
  
const contacts: Section[] = [  
  { title: "A", data: [{ firstName: "John", lastName: "Aaron" }] },  
  {  
    title: "D",  
    data: [  
      { firstName: "John", lastName: "Doe" },  
      { firstName: "Mary", lastName: "Dianne" },  
    ],  
  },
];  
  
const ContactsSectionList = () => {  
  return (  
    <SectionList  
      sections={contacts}  
      renderItem={({ item }) => {  
        return <Text>{item.firstName}</Text>;  
      }}  
      renderSectionHeader={({ section: { title } }) => (  
        <Text style={styles.header}>{title}</Text>  
      )}  
    />  
  );
};

const styles = StyleSheet.create({
  header: {
    fontSize: 32,
    backgroundColor: "#fff",
  },
});  

```

--------------------------------

### Configure Scroll Start Threshold with onStartReachedThreshold

Source: https://shopify.github.io/flash-list/docs/usage

Defines how close the list's top edge must be to the content's start to trigger the `onStartReached` callback. A value of 0.5 means the callback is triggered when the start of the content is within half the visible list length from the top.

```typescript
onStartReachedThreshold?: number;
```

--------------------------------

### Apply Viewability Configuration to FlashList

Source: https://shopify.github.io/flash-list/docs/usage

Example of applying a custom viewability configuration to a FlashList component. This configuration requires user interaction before items are considered viewable and sets a threshold for item visibility.

```jsx
<FlashList
    viewabilityConfig={{
      waitForInteraction: true,
      itemVisiblePercentThreshold: 50,
      minimumViewTime: 1000,
    }}
  ...
>
```

--------------------------------

### Full Example: Animating Item Removal with LayoutAnimation

Source: https://shopify.github.io/flash-list/docs/guides/layout-animation

Demonstrates how to remove an item from a FlashList and animate the removal using React Native's LayoutAnimation. Requires `keyExtractor` to be set on the FlashList.

```javascript
import React, { useRef, useState } from "react";
import { View, Text, Pressable, LayoutAnimation } from "react-native";
import { FlashList } from "@shopify/flash-list";

const List = () => {
  const [data, setData] = useState([1, 2, 3, 4, 5]);

  const list = useRef<FlashList<number> | null>(null);

  const removeItem = (item: number) => {
    setData(
      data.filter((dataItem) => {
        return dataItem !== item;
      })
    );
    // This must be called before `LayoutAnimation.configureNext` in order for the animation to run properly.
    list.current?.prepareForLayoutAnimationRender();
    // After removing the item, we can start the animation.
    LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
  };

  const renderItem = ({ item }: { item: number }) => {
    return (
      <Pressable
        onPress={() => {
          removeItem(item);
        }}
      >
        <View>
          <Text>Cell Id: {item}</Text>
        </View>
      </Pressable>
    );
  };

  return (
    <FlashList
      // Saving reference to the `FlashList` instance to later trigger `prepareForLayoutAnimationRender` method.
      ref={list}
      // This prop is necessary to uniquely identify the elements in the list.
      keyExtractor={(item: number) => {
        return item.toString();
      }}
      renderItem={renderItem}
      data={data}
    />
  );
};

export default List;
```

--------------------------------

### Get Layout Information

Source: https://shopify.github.io/flash-list/docs/usage

Retrieves the current layout dimensions (x, y, width, height) of the FlashList component.

```typescript
getLayout(): { x: number, y: number, width: number; height: number };
```

--------------------------------

### onStartReached

Source: https://shopify.github.io/flash-list/docs/usage

Called once when the scroll position gets within `onStartReachedThreshold` of the start of the content. This is useful for loading older content in infinite scroll scenarios.

```APIDOC
## `onStartReached`

### Description
Called once when the scroll position gets within `onStartReachedThreshold` of the start of the content. Useful for loading older content in infinite scroll scenarios like chat applications.

### Signature
```typescript
onStartReached?: () => void;
```

### Example
```jsx
<FlashList  
  data={messageData}
  onStartReached={() => loadOlderMessages()}
  onStartReachedThreshold={0.1}
  renderItem={({ item }) => <MessageItem message={item} />}
/>
```
```

--------------------------------

### onBlankArea Callback Signature

Source: https://shopify.github.io/flash-list/docs/usage

Callback invoked when blank space is detected during scrolling or initial loading. Reports visible blank space at the start and end of the screen.

```typescript
onBlankArea?: (blankAreaEvent: {
    offsetStart: number;
    offsetEnd: number;
    blankArea: number;
}) => void;

```

--------------------------------

### onStartReachedThreshold

Source: https://shopify.github.io/flash-list/docs/usage

Determines how far from the start of the content the list must be to trigger the `onStartReached` callback. A value of 0.5 means the callback is triggered when the start of the content is within half the visible length of the list from the top.

```APIDOC
## `onStartReachedThreshold`

### Description
How far from the start (in units of visible length of the list) the top edge of the list must be from the start of the content to trigger the `onStartReached` callback. Value of 0.5 will trigger `onStartReached` when the start of the content is within half the visible length of the list from the top.

### Type
```typescript
number;
```
```

--------------------------------

### FlashList with Sticky Header Configuration

Source: https://shopify.github.io/flash-list/docs/usage

Configure sticky header behavior and appearance using the stickyHeaderConfig prop. This example sets a custom offset, backdrop component, zIndex, and enables hiding related cells.

```javascript
<FlashList  
  data={sectionData}  
  stickyHeaderIndices={[0, 10, 20]}  
  stickyHeaderConfig={{
    useNativeDriver: true,
    offset: 50, // Headers stick 50px from top
    backdropComponent: <BlurView style={StyleSheet.absoluteFill} />,
    zIndex: 3,
    hideRelatedCell: true,
  }}  
  renderItem={({ item }) => <ListItem item={item} />}
/>  

```

--------------------------------

### Get Window Size

Source: https://shopify.github.io/flash-list/docs/usage

Returns the current rendered dimensions (width and height) of the visible area of the list.

```typescript
getWindowSize(): { width: number, height: number };
```

--------------------------------

### Trigger Load on Scroll to Start

Source: https://shopify.github.io/flash-list/docs/v2-changes

Implement `onStartReached` to load older data when the user scrolls near the beginning of the list. Set `onStartReachedThreshold` to control the trigger distance.

```javascript
<FlashList  
  data={messageData}  
  onStartReached={() => loadOlderMessages()}  
  onStartReachedThreshold={0.1}  
  renderItem={({ item }) => <MessageItem message={item} />}  
/>  
```

--------------------------------

### Get First Visible Index

Source: https://shopify.github.io/flash-list/docs/usage

Returns the index of the first item that is currently visible within the list's viewport.

```typescript
getFirstVisibleIndex(): number;
```

--------------------------------

### Get First Item Offset

Source: https://shopify.github.io/flash-list/docs/usage

Returns the pixel offset of the first item in the list. This is useful for calculating header sizes or top padding.

```typescript
getFirstItemOffset(): number;
```

--------------------------------

### recordInteraction

Source: https://shopify.github.io/flash-list/docs/usage

Tells the list an interaction has occurred, which should trigger viewability calculations. This is useful when `waitForInteractions` is true and the user has not scrolled. You should typically call `recordInteraction()` when a user, for example, taps on an item or invokes a navigation action.

```APIDOC
## recordInteraction()

### Description
Notifies the list that a user interaction has occurred, triggering viewability calculations. This is particularly important when `waitForInteractions` is enabled and the user has not yet scrolled. Use this method when users interact with list items, such as tapping or navigating.

### Method
`recordInteraction();`
```

--------------------------------

### Get Native Scroll Ref

Source: https://shopify.github.io/flash-list/docs/usage

Provides a reference to the underlying scroll view component, useful for direct manipulation or accessing native methods.

```typescript
getNativeScrollRef(): React.RefObject<CompatScroller>;
```

--------------------------------

### Basic Masonry Layout with FlashList (v2)

Source: https://shopify.github.io/flash-list/docs/guides/masonry

Enable masonry layout by setting the `masonry` prop on `FlashList`. This is suitable for displaying items of different heights in a grid.

```javascript
import React from "react";  
import { View, Text } from "react-native";  
import { FlashList } from "@shopify/flash-list";  
import { DATA } from "./data";  
  
const MyMasonryList = () => {  
  return (  
    <FlashList  
      data={DATA}  
      masonry  
      numColumns={2}  
      renderItem={({ item }) => <Text>{item.title}</Text>}  
    />  
  );
};

```

--------------------------------

### Trigger Action on Scroll Start with onStartReached

Source: https://shopify.github.io/flash-list/docs/usage

Called when the scroll position reaches a threshold near the start of the content. Useful for infinite scrolling scenarios like loading older messages in a chat application. Ensure `onStartReachedThreshold` is set appropriately.

```typescript
onStartReached?: () => void;
```

```jsx
<FlashList
  data={messageData}
  onStartReached={() => loadOlderMessages()}
  onStartReachedThreshold={0.1}
  renderItem={({ item }) => <MessageItem message={item} />}
/>
```

--------------------------------

### Enable Masonry Layout in FlashList

Source: https://shopify.github.io/flash-list/docs/v2-changes

Use the `masonry` prop to enable a grid-like interface with varying item heights. Configure `numColumns` for the desired grid density.

```javascript
<FlashList  
  data={data}  
  masonry  
  numColumns={3}  
  renderItem={({ item }) => <MasonryItem item={item} />}  
/>  
```

--------------------------------

### Get Scrollable Node

Source: https://shopify.github.io/flash-list/docs/usage

Retrieves the native scrollable node from the underlying scroll view.

```typescript
getScrollableNode(): any;
```

--------------------------------

### onEndReached

Source: https://shopify.github.io/flash-list/docs/usage

Callback called once when the scroll position gets within `onEndReachedThreshold` of the rendered content.

```APIDOC
## onEndReached

### Description
Callback called once when the scroll position gets within `onEndReachedThreshold` of the rendered content.

### Signature
`() => void`
```

--------------------------------

### Optimize Item Mapping with useMappingHelper

Source: https://shopify.github.io/flash-list/docs/v2-changes

Utilize useMappingHelper to generate optimal mapping keys for items when using .map() for improved recycling and performance in FlashList.

```javascript
import { useMappingHelper } from "@shopify/flash-list";

const MyComponent = ({ items }) => {
  const { getMappingKey } = useMappingHelper();

  return (
    <FlashList
      data={items}
      renderItem={({ item }) => <ItemComponent item={item} />}
    />
  );
};

// When mapping over items inside components:
const NestedList = ({ items }) => {
  const { getMappingKey } = useMappingHelper();

  return (
    <View>
      {items.map((item, index) => (
        <Text key={getMappingKey(item.id, index)}>{item.title}</Text>
      ))}
    </View>
  );
};

```

--------------------------------

### Basic FlashList Implementation

Source: https://shopify.github.io/flash-list/docs/usage

This snippet demonstrates the fundamental usage of FlashList by replacing a standard FlatList component. Ensure you import FlashList from '@shopify/flash-list'.

```javascript
import React from "react";  
import { View, Text, StatusBar } from "react-native";  
import { FlashList } from "@shopify/flash-list";  
  
const DATA = [  
  {  
    title: "First Item",  
  },  
  {  
    title: "Second Item",  
  },  
];  
  
const MyList = () => {  
  return (  
    <FlashList  
      data={DATA}  
      renderItem={({ item }) => <Text>{item.title}</Text>}  
    />  
  );  
};

```

--------------------------------

### Get Scroll Responder

Source: https://shopify.github.io/flash-list/docs/usage

Returns the scroll responder object associated with the underlying scroll view.

```typescript
getScrollResponder(): any;
```

--------------------------------

### Basic FlashList Benchmarking

Source: https://shopify.github.io/flash-list/docs/guides/list-profiling

Use the useBenchmark hook for automatic performance measurement of a FlashList. Pass the ref of your FlashList and a callback function to receive benchmark results.

```typescript
import { useRef } from "react";
import { FlashList, FlashListRef, useBenchmark } from "@shopify/flash-list";

function MyList() {
  const flashListRef = useRef<FlashListRef<MyDataType>>(null);

  // Basic benchmark setup
  useBenchmark(flashListRef, (result) => {
    console.log("Benchmark complete:", result.formattedString);
  });

  return <FlashList ref={flashListRef} data={data} renderItem={renderItem} />;
}

```

--------------------------------

### Initial Scroll Index Parameters

Source: https://shopify.github.io/flash-list/docs/usage

Configure `initialScrollIndexParams` with `viewOffset` for scroll position adjustments.

```typescript
initialScrollIndexParams?: { viewOffset?: number };
```

--------------------------------

### Get Visible Indices

Source: https://shopify.github.io/flash-list/docs/usage

Returns an array containing the indices of all items currently visible within the list.

```typescript
getVisibleIndices(): number[];
```

--------------------------------

### onEndReached Callback Signature

Source: https://shopify.github.io/flash-list/docs/usage

Callback invoked once when the scroll position gets within onEndReachedThreshold of the rendered content.

```typescript
onEndReached?: () => void;

```

--------------------------------

### FlashList Implementation for Sections

Source: https://shopify.github.io/flash-list/docs/guides/section-list

Illustrates how to render a list with section headers using FlashList by checking the item type within renderItem and using getItemType for performance optimization.

```typescript
const ContactsFlashList = () => {  
  return (  
    <FlashList  
      data={contacts}  
      renderItem={({ item }) => {  
        if (typeof item === "string") {  
          // Rendering header  
          return <Text style={styles.header}>{item}</Text>;  
        } else {  
          // Render item  
          return <Text>{item.firstName}</Text>;  
        }  
      }}  
      getItemType={(item) => {  
        // To achieve better performance, specify the type based on the item  
        return typeof item === "string" ? "sectionHeader" : "row";  
      }}  
    />  
  );
};

```

--------------------------------

### useMappingHelper Hook

Source: https://shopify.github.io/flash-list/docs/v2-changes

Provides a function to create optimal mapping keys for items when using `.map()` in render methods, ensuring optimized recycling and performance for FlashList.

```APIDOC
## useMappingHelper

### Description
This hook returns a function that helps create optimal mapping keys for items when using `.map()` in your render methods. Using this ensures optimized recycling and performance for FlashList.

### Usage
```javascript
import { useMappingHelper } from "@shopify/flash-list";

const MyComponent = ({ items }) => {
  const { getMappingKey } = useMappingHelper();

  return (
    <FlashList
      data={items}
      renderItem={({ item }) => <ItemComponent item={item} />}
    />
  );
};

// When mapping over items inside components:
const NestedList = ({ items }) => {
  const { getMappingKey } = useMappingHelper();

  return (
    <View>
      {items.map((item, index) => (
        <Text key={getMappingKey(item.id, index)}>{item.title}</Text>
      ))}
    </View>
  );
};
```
```

--------------------------------

### Prepare for LayoutAnimation Render

Source: https://shopify.github.io/flash-list/docs/guides/layout-animation

Call `prepareForLayoutAnimationRender` before `LayoutAnimation.configureNext` for animations to work. This method is called on the FlashList instance.

```javascript
listRef.current?.prepareForLayoutAnimationRender();
// After removing the item, we can start the animation.
LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
```

--------------------------------

### Sticky Header Configuration Object

Source: https://shopify.github.io/flash-list/docs/usage

Defines the configuration options for sticky header behavior and appearance in FlashList. All properties are optional.

```typescript
stickyHeaderConfig?: {
  useNativeDriver?: boolean;
  offset?: number;
  backdropComponent?: React.ComponentType<any> | React.ReactElement | null;
  zIndex?: number;
  hideRelatedCell?: boolean;
};

```

--------------------------------

### Implement Local State with useLayoutState

Source: https://shopify.github.io/flash-list/docs/v2-changes

Use useLayoutState for state that affects item layout, ensuring smooth visual updates. It communicates state changes directly to FlashList.

```javascript
import { useLayoutState } from "@shopify/flash-list";

const MyItem = ({ item }) => {
  const [isExpanded, setIsExpanded] = useLayoutState(false);
  const height = isExpanded ? 150 : 80;

  return (
    <Pressable onPress={() => setIsExpanded(!isExpanded)}>
      <View style={{ height, padding: 16 }}>
        <Text>{item.title}</Text>
      </View>
    </Pressable>
  );
};

```

--------------------------------

### getWindowSize

Source: https://shopify.github.io/flash-list/docs/usage

Returns the current dimensions (width and height) of the visible viewport of the FlashList.

```APIDOC
## getWindowSize()

### Description
Returns an object containing the current width and height of the visible area of the FlashList, representing its rendered dimensions.

### Method
`getWindowSize(): { width: number, height: number };`
```

--------------------------------

### Migrate MasonryFlashList to FlashList with masonry prop

Source: https://shopify.github.io/flash-list/docs/v2-migration

Replace MasonryFlashList with FlashList and use the 'masonry' prop. The getColumnFlex prop is not supported in v2.

```jsx
// v1  
- import { MasonryFlashList } from "@shopify/flash-list";  
  
- <MasonryFlashList  
-   data={data}  
-   renderItem={renderItem}  
-   numColumns={3}  
-   estimatedItemSize={100}  
- />  
  
// v2  
+ import { FlashList } from "@shopify/flash-list";  
  
+ <FlashList  
+   data={data}  
+   renderItem={renderItem}  
+   numColumns={3}  
+   masonry  
+ />  
```

--------------------------------

### Use `useMappingHelper` for Keys in Maps

Source: https://shopify.github.io/flash-list/docs/fundamentals/performance

When mapping over arrays within FlashList item components, use the `useMappingHelper` hook to generate stable keys. This hook ensures that keys are suitable for both FlashList's recycling mechanism and React's reconciliation process.

```javascript
import { useMappingHelper } from "@shopify/flash-list";

const MyItem = ({ item }) => {
  const { getMappingKey } = useMappingHelper();

  return (
    <>
      {item.users.map((user, index) => (
        <Text key={getMappingKey(user.id, index)}>{user.name}</Text>
      ))}
    </>
  );
};

```

--------------------------------

### getLayout

Source: https://shopify.github.io/flash-list/docs/usage

Returns the current layout information (position and dimensions) of the FlashList component.

```APIDOC
## getLayout()

### Description
Returns an object containing the current layout details of the FlashList, including its x and y coordinates, width, and height.

### Method
`getLayout(): { x: number, y: number, width: number; height: number };`
```

--------------------------------

### onLoad

Source: https://shopify.github.io/flash-list/docs/usage

Event raised once the list has drawn items on the screen, reporting the time it took to draw them.

```APIDOC
## onLoad

### Description
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. This is required because FlashList doesn't render items in the first cycle. Items are drawn after it measures itself at the end of first render.

### Signature
`(info: { elapsedTimeInMs: number }) => void`

### Note
Please note that the event is not fired if ListEmptyComponent is rendered.
```

--------------------------------

### Number of Columns Prop

Source: https://shopify.github.io/flash-list/docs/usage

Configure `numColumns` for multi-column layouts. Requires `horizontal={false}` and assumes items have uniform height.

```typescript
numColumns?: number;
```

--------------------------------

### Masonry Layout Prop

Source: https://shopify.github.io/flash-list/docs/usage

Enable `masonry` layout for grid interfaces with varying item heights. Requires `numColumns` greater than 1.

```typescript
masonry?: boolean;
```

--------------------------------

### useLayoutState Hook

Source: https://shopify.github.io/flash-list/docs/v2-changes

Similar to `useState` but communicates state changes to FlashList, useful for resizing child components based on local state. Item layout changes are detected smoothly.

```APIDOC
## useLayoutState

### Description
This hook is similar to `useState` but communicates state changes to FlashList, which is useful for resizing child components based on local state. Item layout changes will still be detected using the `onLayout` callback in the absence of `useLayoutState`, which might not look as smooth on a case-by-case basis.

### Usage
```javascript
import { useLayoutState } from "@shopify/flash-list";

const MyItem = ({ item }) => {
  const [isExpanded, setIsExpanded] = useLayoutState(false);
  const height = isExpanded ? 150 : 80;

  return (
    <Pressable onPress={() => setIsExpanded(!isExpanded)}>
      <View style={{ height, padding: 16 }}>
        <Text>{item.title}</Text>
      </View>
    </Pressable>
  );
};
```
```

--------------------------------

### useNativeDriver Property

Source: https://shopify.github.io/flash-list/docs/usage

Specifies whether to use the native driver for sticky header animations. Defaults to true.

```typescript
useNativeDriver?: boolean;

```

--------------------------------

### Manual FlashList Benchmark Control

Source: https://shopify.github.io/flash-list/docs/guides/list-profiling

Control the benchmark execution manually using the `startManually` option. This allows you to trigger the benchmark via a button press and configure parameters like repeat count and speed multiplier.

```typescript
const { startBenchmark, isBenchmarkRunning } = useBenchmark(
  flashListRef,
  (result) => {
    if (!result.interrupted) {
      Alert.alert("Benchmark Complete", result.formattedString);
    }
  },
  {
    startManually: true,
    repeatCount: 3,
    speedMultiplier: 1.5,
  }
);

// Trigger benchmark on button press
<Button
  title={isBenchmarkRunning ? "Running..." : "Start Benchmark"}
  onPress={startBenchmark}
  disabled={isBenchmarkRunning}
/>;
```

--------------------------------

### onChangeStickyIndex

Source: https://shopify.github.io/flash-list/docs/usage

Callback invoked when the currently displayed sticky header changes as you scroll. Receives the current sticky header index and the previous sticky header index.

```APIDOC
## onChangeStickyIndex

### Description
Callback invoked when the currently displayed sticky header changes as you scroll. Receives the current sticky header index and the previous sticky header index. This is useful for tracking which header is currently stuck at the top while scrolling. The index refers to the position of the item in your data array that's being used as a sticky header.

### Signature
`(current: number, previous: number) => void`

### Example
```jsx
<FlashList  
  data={sectionData}  
  stickyHeaderIndices={[0, 10, 20]}  
  onChangeStickyIndex={(current, previous) => {
    console.log(`Sticky header changed from ${previous} to ${current}`);
  }}
  renderItem={({ item }) => <ListItem item={item} />}
/>
```
```

--------------------------------

### style

Source: https://shopify.github.io/flash-list/docs/usage

Applies styling to the FlashList's parent container. It is recommended to avoid using padding here, as it can affect the internal ScrollView's size. In most cases, `contentContainerStyle` is sufficient.

```APIDOC
## `style`

### Description
Style for the FlashList's parent container. It's highly recommended to avoid adding padding which can impact the size of the ScrollView inside. We operate on the assumption that the size of parent view and ScrollView is the same. In most cases, `contentContainerStyle` should be enough, so avoid using this.

### Type
```typescript
StyleProp<ViewStyle>;
```
```

--------------------------------

### progressViewOffset

Source: https://shopify.github.io/flash-list/docs/usage

Specifies an offset needed for the loading indicator to display correctly.

```APIDOC
## `progressViewOffset`

### Description
Set this when offset is needed for the loading indicator to show correctly.

### Type
```typescript
number;
```
```

--------------------------------

### Implement getItemType for Optimized Recycling

Source: https://shopify.github.io/flash-list/docs/fundamentals/performance

Implement the getItemType prop in FlashList to leverage separate recycling pools based on item type, improving re-render performance.

```typescript
const MessageList = () => {
  return (
    <FlashList 
      renderItem={MessageItem} 
      estimatedItemSize={200} 
      getItemType={(item) => {
        return item.type;
      }}
    />
  );
};

```

--------------------------------

### stickyHeaderConfig

Source: https://shopify.github.io/flash-list/docs/usage

Configuration object for sticky header behavior and appearance. Allows customization of native driver usage, offset, backdrop component, zIndex, and hiding related cells.

```APIDOC
## stickyHeaderConfig

### Description
Configuration object for sticky header behavior and appearance. All properties are optional.

### Properties
- **useNativeDriver** (boolean) - Optional - If true, the sticky headers will use native driver for animations. Default is `true`.
- **offset** (number) - Optional - Offset from the top of the list where sticky headers should stick. Default is `0`.
- **backdropComponent** (React.ComponentType<any> | React.ReactElement | null) - Optional - Component to render behind sticky headers. Useful for creating visual separation or effects like backgrounds with blur.
- **zIndex** (number) - Optional - zIndex applied to the sticky header container. Default is `2`.
- **hideRelatedCell** (boolean) - Optional - When a sticky header is displayed, the cell associated with it is hidden. Default is `false`.

### Example
```jsx
<FlashList  
  data={sectionData}  
  stickyHeaderIndices={[0, 10, 20]}  
  stickyHeaderConfig={{
    useNativeDriver: true,
    offset: 50, // Headers stick 50px from top
    backdropComponent: <BlurView style={StyleSheet.absoluteFill} />,
    zIndex: 3,
    hideRelatedCell: true,
  }}
  renderItem={({ item }) => <ListItem item={item} />}
/>
```
```

--------------------------------

### Define ViewabilityConfig Interface

Source: https://shopify.github.io/flash-list/docs/usage

Defines the structure for viewability configuration, specifying thresholds and interaction requirements.

```typescript
interface ViewabilityConfig: {
  minimumViewTime: number;
  viewAreaCoveragePercentThreshold: number;
  itemVisiblePercentThreshold: number;
  waitForInteraction: boolean;
}

viewabilityConfig?: ViewabilityConfig;
```

--------------------------------

### FlashList Data Structure for Sections

Source: https://shopify.github.io/flash-list/docs/guides/section-list

Shows how to flatten the data structure for FlashList, combining section headers and data items into a single array.

```typescript
const contacts: (string | Contact)[] = [  
  "A",  
  { firstName: "John", lastName: "Aaron" },  
  "D",  
  { firstName: "John", lastName: "Doe" },  
  { firstName: "Mary", lastName: "Dianne" },  
];  

```

--------------------------------

### onRefresh

Source: https://shopify.github.io/flash-list/docs/usage

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality.

```APIDOC
## onRefresh

### Description
If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the `refreshing` prop correctly.

### Signature
`() => void`
```

--------------------------------

### prepareForLayoutAnimationRender

Source: https://shopify.github.io/flash-list/docs/usage

Call this method before running layout animations, such as when animating an element when deleting it. This method disables recycling for the next frame so that layout animations run well. Avoid using this when making large changes to the data as the list might draw too much to run animations since the method disables recycling temporarily. Single item insertions or deletions should animate smoothly. The render after animation will enable recycling again and you can stop avoiding making large data changes.

```APIDOC
## prepareForLayoutAnimationRender()

### Description
Disables recycling for the next frame to ensure smooth layout animations, typically used before animating element deletions or insertions. Note that this temporarily disables recycling, so avoid large data changes during this period.

### Method
`prepareForLayoutAnimationRender(): void;`
```

--------------------------------

### Manage Resetting State with useRecyclingState

Source: https://shopify.github.io/flash-list/docs/v2-changes

Use useRecyclingState to manage local item state that needs to reset based on dependencies. It includes the functionality of useLayoutState.

```javascript
import { useRecyclingState } from "@shopify/flash-list";

const GridItem = ({ item }) => {
  const [isExpanded, setIsExpanded] = useRecyclingState(
    false,
    [item.id],
    () => {
      // runs on reset. Can be used to reset scroll positions of nested horizontal lists
    },
  );
  const height = isExpanded ? 100 : 50;

  return (
    <Pressable onPress={() => setIsExpanded(!isExpanded)}>
      <View style={{ height, backgroundColor: item.color }}>
        <Text>{item.title}</Text>
      </View>
    </Pressable>
  );
};

```

--------------------------------

### Using useSharedValue with FlashList

Source: https://shopify.github.io/flash-list/docs/guides/reanimated

Demonstrates how to use `useSharedValue` and reset its value using `useEffect` when a view is recycled for a new item. This is crucial for managing state in performant lists.

```typescript
import React, { useEffect } from "react";  
import Animated, { useSharedValue } from "react-native-reanimated";  
import { FlashList } from "@shopify/flash-list";  
  
const Item = ({ item }: { item: { id: string } }) => {  
  const myValue = useSharedValue(0);  
  useEffect(() => {  
    // Reset value when id changes (view was recycled for another item)  
    myValue.value = 0;  
  }, [item.id, myValue]);  
  return <Animated.View />;  
};  
  
const MyList = () => {  
  return <FlashList renderItem={Item} />;  
};  

```

--------------------------------

### recomputeViewableItems

Source: https://shopify.github.io/flash-list/docs/usage

Retriggers viewability calculations. Useful to imperatively trigger viewability calculations.

```APIDOC
## recomputeViewableItems()

### Description
Imperatively triggers a recalculation of which items are currently viewable within the list.

### Method
`recomputeViewableItems();`
```

--------------------------------

### getFirstVisibleIndex

Source: https://shopify.github.io/flash-list/docs/usage

Returns the index of the first item that is currently visible within the FlashList viewport.

```APIDOC
## getFirstVisibleIndex()

### Description
Retrieves and returns the index of the very first item that is currently visible on the screen within the FlashList.

### Method
`getFirstVisibleIndex(): number;`
```

--------------------------------

### Prepare for Layout Animation Render

Source: https://shopify.github.io/flash-list/docs/usage

Call this method before running layout animations, such as when animating an element during deletion. It disables recycling for the next frame to ensure smooth animations. Avoid using this for large data changes as it can temporarily impact performance.

```typescript
prepareForLayoutAnimationRender(): void;
```

--------------------------------

### Use useLayoutState Hook

Source: https://shopify.github.io/flash-list/docs/usage

Use useLayoutState for state management that communicates changes to FlashList, useful for resizing child components. It's an alternative to useState when direct state-to-layout communication is needed.

```javascript
const [state, setState] = useLayoutState(initialState);
```

```javascript
import { useLayoutState } from "@shopify/flash-list";

const MyItem = ({ item }) => {
  const [isExpanded, setIsExpanded] = useLayoutState(false);
  const height = isExpanded ? 150 : 80;

  return (
    <Pressable onPress={() => setIsExpanded(!isExpanded)}>
      <View style={{ height, padding: 16 }}>
        <Text>{item.title}</Text>
      </View>
    </Pressable>
  );
};
```

--------------------------------

### onChangeStickyIndex Callback Signature

Source: https://shopify.github.io/flash-list/docs/usage

Callback invoked when the currently displayed sticky header changes. Receives the current and previous sticky header indices.

```typescript
onChangeStickyIndex?: (current: number, previous: number) => void;

```

--------------------------------

### Configure Scroll Position Maintenance

Source: https://shopify.github.io/flash-list/docs/v2-changes

Utilize `maintainVisibleContentPosition` for smoother scroll behavior, especially in chat interfaces. `startRenderingFromBottom` is useful for chat UIs, and `autoscrollToBottomThreshold` defines the scroll trigger point.

```javascript
<FlashList  
  data={chatMessages}  
  maintainVisibleContentPosition={{
    autoscrollToBottomThreshold: 0.2,
    startRenderingFromBottom: true,
  }}  
  renderItem={({ item }) => <ChatMessage message={item} />}  
/>  
```

--------------------------------

### Customizing Item Layout with overrideItemLayout

Source: https://shopify.github.io/flash-list/docs/guides/masonry

Use `overrideItemLayout` to customize item layout, such as setting the number of columns an item should span. Size estimates are no longer required in v2.

```javascript
import React from "react";  
import { View, Text, Image } from "react-native";  
import { FlashList } from "@shopify/flash-list";  
  
interface MasonryItem {  
  id: string;  
  title: string;  
  height: number;  
  span: number; // Number of columns this item should span  
  imageUrl: string;  
}

const MyMasonryList = () => {  
  return (  
    <FlashList  
      data={data}  
      masonry  
      numColumns={3}  
      overrideItemLayout={(layout, item) => {  
        // Set the span based on the item's span property  
        layout.span = item.span;  
        // Note: In v2, size estimates are no longer needed in overrideItemLayout  
        // The actual height is determined by the rendered component  
      }}  
      renderItem={({ item }) => (  
        <View style={{ backgroundColor: "#f0f0f0", margin: 4 }}>  
          <Image source={{ uri: item.imageUrl }} style={{ flex: 1 }} />  
          <Text>{item.title}</Text>  
        </View>  
      )}  
      keyExtractor={(item) => item.id}  
    />  
  );
};

```

--------------------------------

### scrollToTop

Source: https://shopify.github.io/flash-list/docs/usage

Scrolls the list back to the very top. Animation can be optionally enabled.

```APIDOC
## scrollToTop

### Description
Scrolls the FlashList content to the top position. You can choose to animate this scroll action.

### Method
`scrollToTop(params?: { animated?: boolean }): void;`

### Parameters
#### Query Parameters
- **animated** (boolean) - Optional - Specifies whether the scroll to top should be animated.
```

--------------------------------

### Basic Usage of LayoutCommitObserver

Source: https://shopify.github.io/flash-list/docs/fundamentals/layout-commit-observer

Wrap your component tree with LayoutCommitObserver and provide a callback to handle layout completion. This is useful when you need to perform actions after all internal lists have rendered.

```javascript
import { LayoutCommitObserver } from "@shopify/flash-list";  
  
function MyScreen() {  
  const handleLayoutComplete = () => {  
    console.log("All FlashLists have completed their initial layout!");  
    // Perform any post-layout actions here  
  };  
  
  return (  
    <LayoutCommitObserver onCommitLayoutEffect={handleLayoutComplete}>  
      <View>  
        <FlashList data={data1} renderItem={renderItem1} />  
        <FlashList data={data2} renderItem={renderItem2} />  
      </View>  
    </LayoutCommitObserver>  
  );  
}
```

--------------------------------

### Define ViewabilityConfigCallbackPairs Type

Source: https://shopify.github.io/flash-list/docs/usage

Defines the structure for an array of viewability configuration and callback pairs. Each pair allows associating a specific viewability configuration with a custom callback function.

```typescript
type ViewabilityConfigCallbackPairs = ViewabilityConfigCallbackPair[];

interface ViewabilityConfigCallbackPair {
  viewabilityConfig: ViewabilityConfig;
  onViewableItemsChanged:
    | ((info: { viewableItems: ViewToken[]; changed: ViewToken[] }) => void)
    | null;
}

viewabilityConfigCallbackPairs: ViewabilityConfigCallbackPairs | undefined;
```

--------------------------------

### onCommitLayoutEffect

Source: https://shopify.github.io/flash-list/docs/usage

Callback called before layout is committed. Can be used to measure list and make changes before paint.

```APIDOC
## onCommitLayoutEffect

### Description
Callback called before layout is committed. Can be used to measure list and make changes before paint.

### Signature
`() => void`

### Warning
Doing setState inside the callback can lead to infinite loops. Make sure FlashList's props are memoized.
```

--------------------------------

### onLoad Callback Signature

Source: https://shopify.github.io/flash-list/docs/usage

Callback raised once the list has drawn items on the screen, reporting the time taken in milliseconds. Not fired if ListEmptyComponent is rendered.

```typescript
onLoad: (info: { elapsedTimeInMs: number }) => void;

```

--------------------------------

### Calculating Sticky Header Indices for FlashList

Source: https://shopify.github.io/flash-list/docs/guides/section-list

Provides the logic to compute the `stickyHeaderIndices` array required for enabling sticky section headers in FlashList, based on the flattened data structure.

```typescript
const stickyHeaderIndices = contacts  
  .map((item, index) => {  
    if (typeof item === "string") {  
      return index;  
    } else {  
      return null;  
    }  
  })  
  .filter((item) => item !== null) as number[];  

```

--------------------------------

### getFirstItemOffset

Source: https://shopify.github.io/flash-list/docs/usage

Returns the pixel offset of the first item in the list. This is useful for calculating header sizes or top padding.

```APIDOC
## getFirstItemOffset()

### Description
Returns the calculated pixel offset from the start of the scrollable content to the beginning of the first item. This value is helpful for determining header heights or required top padding.

### Method
`getFirstItemOffset(): number;`
```

--------------------------------

### Record User Interaction

Source: https://shopify.github.io/flash-list/docs/usage

Informs the list that an interaction has occurred, triggering viewability calculations. Typically called when a user taps an item or initiates a navigation action.

```typescript
recordInteraction();
```

--------------------------------

### offset Property

Source: https://shopify.github.io/flash-list/docs/usage

Sets the offset from the top of the list where sticky headers should stick. Useful for fixed headers or navigation bars. Defaults to 0.

```typescript
offset?: number;

```

--------------------------------

### refreshing

Source: https://shopify.github.io/flash-list/docs/usage

A boolean prop to indicate whether the list is currently waiting for new data from a refresh operation.

```APIDOC
## `refreshing`

### Description
Set this true while waiting for new data from a refresh.

### Type
```typescript
boolean;
```
```

--------------------------------

### optimizeItemArrangement Prop

Source: https://shopify.github.io/flash-list/docs/guides/masonry

When `masonry` layout is enabled, `optimizeItemArrangement` (defaults to `true`) attempts to reduce differences in column heights by reordering items.

```typescript
optimizeItemArrangement?: boolean;  

```
Tokens:
Raw