npm / @shopify/flash-list
@shopify/flash-list
What changed in @shopify/flash-list 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-14.
17 breaking6 deprecations21 new APIs and options6 behavior and defaults17 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@shopify/flash-list 267 changes
Breaking changes 17
Removes x,y from measureParentSize, fixing Fabric sticky header offset.
CellContainer is no longer exported; replace it with React Native's View.
This prop is no longer supported because v2 has no auto layout.
This prop is no longer needed and should be removed.
Remove this size-estimation prop; FlashList v2 automatically handles sizing.
Remove this size-estimation prop; FlashList v2 automatically handles sizing.
Remove this size-estimation prop; FlashList v2 automatically handles sizing.
Use the masonry prop to enable masonry layout on FlashList.
Use FlashListRef as the ref type for FlashList instead of FlashList.
This MasonryFlashList API is not supported in v2.
getColumnFlex from MasonryFlashList will not be supported with the v2 masonry prop.
In grid layout, a shorter item beside a taller item now matches the taller item's height.
Horizontal lists are much improved, items can resize within them, and an extra item is no longer rendered to measure list height.
FlashList no longer asks for estimates, making it easier to use.
This prop is no longer supported and should be removed from FlashList components.
This callback no longer supports setting size; it only supports span changes.
FlashList v2 only works on top of React Native's new architecture.
Deprecations 6
disableAutoLayout is deprecated because there is no auto layout in v2.
estimatedFirstItemOffset is deprecated because it is no longer used.
estimatedItemSize is deprecated because it is no longer used.
estimatedListSize is deprecated because it is no longer used.
MasonryFlashList is deprecated; migrate to FlashList with the masonry prop.
onBlankArea is deprecated; the project has no plans to add or continue supporting it.
New APIs and options 21
Adds configuration for sticky header zIndex.
Adds an inverted prop.
Introduces onChangeStickyIndex.
Introduces sticky header configuration for offset, backdrop, native driver, and hiding the cell.
The FlashList ref exposes more methods, including getVisibleIndices and getLayout.
A helper component observes FlashList layout commits, including when multiple FlashLists in a component tree have finished committing layout.
Controls whether scrolling is animated whenever autoscrollToBottom is triggered; the default is true.
Automatically scroll to maintain position when content is added at the bottom.
Automatically scroll to maintain position when content is added at the top.
Set disabled to true to turn off maintainVisibleContentPosition.
When true, the initial render starts from the bottom, which is useful for chat interfaces.
Sets the maximum number of items in the recycle pool; the notes say it is only needed when the number of item types is huge.
A callback runs before layout is committed and can measure the list and make changes before paint; setting state inside it can cause infinite loops.
A callback is called when the scroll position gets within onStartReachedThreshold of the start of the content.
Configures how far from the start the top edge of the list must be to trigger onStartReached.
When enabled with masonry layout, item order can be modified to reduce differences in column height.
Styles the FlashList parent container; padding is discouraged because it can affect the size of the ScrollView inside.
Exposes helpers to access the FlashList ref and the ScrollView ref, including from child components or CellRendererComponent.
A useState-like hook communicates state changes to FlashList and can help resize child components smoothly.
Returns a helper for creating optimal mapping keys when using .map() in render methods, supporting optimized recycling and performance.
A useState-like hook resets state when dependencies change without an additional setState call and includes useLayoutState functionality.
Behavior and default changes 6
This prop is enabled by default for better scroll position handling.
overrideItemLayout can now be used with masonry.
FlashList adds support for RTL layouts.
scrollToIndex is much more precise.
scrollToItem is much more precise.
Sticky headers use an Animated implementation so minor gaps between them while scrolling are no longer visible.
Fixes and other changes 17
Fixes blank rows during fast scrolling when drawDistance is small.
Disables removeClippedSubviews to prevent an Android crash.
Fixes an autoscroll race when scrolling to an index.
Guards against a zero window size in bound detection.
Enables maintainVisibleContentPosition for horizontal lists.
Adds a type to the RecyclerViewProps export statement to comply with isolatedModules.
Maintains scroll position when prepending large items.
Reads the initialScrollIndex offset after layout recompute.
Average measurement is now always positive.
Supports React.memo, forwardRef, and class components in all component props.
Suppresses grid separators in the last row to prevent height mismatch.
Eliminates scroll jitter when prepending items at the bottom.
Respects waitForInteraction when initialScrollIndex is set.
Filters stale indices from layoutInfo after truncation.
Fixes an index-out-of-bounds issue in viewability computation.
Fixes sticky header lists disappearing when currentStickyIndex is -1 on RN 0.83.
The contentContainerStyle prop is now fully supported.