Usage

The FlatList component is a high-performance list component that efficiently renders only the items currently visible on the screen, regardless of the size of the data set. It is ideal for rendering basic, flat lists and supports the most handy features like:

• Full tokenization support.
• Fully cross-platform.
• Optional horizontal mode.
• Configurable viewability callbacks.
• Header support.
• Footer support.
• Separator support.
• Pull to Refresh.
• Scroll loading.
• ScrollToIndex support.
• Multiple column support.

Tip

If you need section support, consider using the SectionList component.

Best Practices

• Use Memoization: Use React.memo()opens in a new window to avoid unnecessary re-renders of list items.
• Pagination: For large datasets, implement pagination with onEndReached to load additional data dynamically.
• Key Extraction: Ensure keyExtractor returns a unique and stable key to avoid performance degradation caused by reordering or re-rendering items unnecessarily.

Considerations

FlatList is a convenience wrapper around VirtualizedList, and thus inherits its props (as well as those of ScrollView) that aren't explicitly listed here, along with the following caveats:

• Internal State: Internal state is not preserved when content scrolls out of the render window. Ensure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
• Prop Updates: This is a PureComponent meaning it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
• Item Rendering: In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application.
• Key Management: By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Accessibility Considerations

• Screen Reader Support: Ensure that list items have accessible labels and descriptions, especially if they contain interactive elements.
• Focus Management: When dynamically loading data, manage focus properly so users can navigate the list without losing track of their position.

Performance Considerations

• Windowing: Use initialNumToRender and maxToRenderPerBatch props to control how many items are rendered initially and in each batch to avoid overloading the UI with too many items at once.
• Recycling Cells: Consider using CellRenderComponent to recycle rendered items and improve rendering performance for large lists.
• Avoid Excessive Renders: Leverage shouldComponentUpdate to prevent unnecessary renders of list items.

FlatList Classes

Class Name	Description
abyss-flat-list-root	FlatList root element.

FlatList Props

Extends React Native - FlatListopens in a new window props.

Name	Type	Default	Description
columnWrapperStyle	Style<"View">		Optional custom style for multi-item rows generated when numColumns > 1
contentContainerStyle	Style<"View">		These styles will be applied to the scroll view content container which wraps all of the child views.
contentInset	Insets | undefined		The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.
contentOffset	PointProp | undefined		Used to manually set the starting scroll offset. The default value is { x: 0, y: 0 }
disableDefaultProviderProps	boolean | undefined	false	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
endFillColor	Color | undefined		Sometimes a ScrollView takes up more space than its content fills. When this is the case, this prop will fill the rest of the ScrollView with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.
fadingEdgeLength	Space | undefined		Fades out the edges of the scroll content. If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show. The default value is 0.
hitSlop	number | Insets | null | undefined		This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. If a Touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{ top: 10, bottom: 10, left: 0, right: 0 }} NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.
ListFooterComponentStyle	Style<"View">		Styling for internal View for ListFooterComponent
ListHeaderComponentStyle	Style<"View">		Styling for internal View for ListHeaderComponent
rootTestID	string | undefined		Adds the passed in test ID to the root element of the component.
style	Style<"FlatList">		FlatList style properties with Abyss token mapping
styles	Styles<FlatListClasses> | undefined		Add custom styles to component by class name with Abyss token mapping
testID	string | undefined		Used to locate this view in end-to-end tests. Using this prop will append -abyss and the name of the element class at the end of the testID passed in. If you want to only use string passed in on the root element, use the rootTestID prop instead.