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() 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 - FlatList props.

Name	Type	Default	Required	Description
columnWrapperStyle	Abyss.Style<'View'> | undefined	-	-	Optional custom style for multi-item rows generated when numColumns > 1
contentContainerStyle	Abyss.Style<'View'> | undefined	-	-	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 }
endFillColor	Abyss.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	Abyss.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	Abyss.Style<'View'> | undefined	-	-	Styling for internal View for ListFooterComponent
ListHeaderComponentStyle	Abyss.Style<'View'> | undefined	-	-	Styling for internal View for ListHeaderComponent
style	Abyss.Style<'FlatList'> | undefined	-	-	FlatList style properties with Abyss token mapping