Skip to content

Legend List 3.0 adds Web support and a SectionList component

updated

Legend List version 3 introduces first-class Web support and a new SectionList component, along with several API improvements. A migration guide covers the breaking changes from v2.

New in v3

Web support: DOM-native rendering that does not require a React Native dependency, using the same virtualization core as React Native, with web examples and docs.

SectionList: @legendapp/list/section-list offers a React Native-compatible API, scrollToLocation support and sticky section headers powered by stickyHeaderIndices.

Always render: alwaysRender keeps selected items mounted outside the virtualization window.

Scroll and metrics APIs:

  • initialScrollAtEnd for chat and feeds
  • anchoredEndSpace to reserve readable space after a chat or feed anchor row
  • contentInsetEndAdjustment for floating composers and overlay UI at the end of a list
  • useKeyboardChatComposerInset for React Native keyboard chat composers
  • onMetricsChange for header/footer size changes
  • getState() now exposes listeners, element access and scroll velocity

Breaking changes from v2

  • The root @legendapp/list component export has been removed. Use @legendapp/list/react-native for React Native and @legendapp/list/react for React (Web).
  • Scroll-position stabilization on size changes is now on by default, equivalent to maintainVisibleContentPosition={{ size: true, data: false }}. Options such as {{ data: true }}, {{ size: false }}, true and false toggle the behavior.
  • getFixedItemSize is now (item, index, type). getEstimatedItemSize and suggestEstimatedItemSize have been removed; the latter is replaced by ref.current?.getState().getAverageItemSizes().
  • stickyIndices has been removed in favor of stickyHeaderIndices.
  • Keyboard integration moves from @legendapp/list/keyboard-controller to @legendapp/list/keyboard, which exports KeyboardAwareLegendList, useKeyboardScrollToEnd and useKeyboardChatComposerInset. LegendList is no longer exported there. KeyboardAvoidingLegendList is available from @legendapp/list/keyboard-legacy.
  • renderItem is called directly as a render callback. Hook-using item components should be returned from the callback, e.g. renderItem={({ item }) => <Row item={item} />}, rather than passed as renderItem={Row}.
  • scrollIndexIntoView, scrollItemIntoView, scrollToEnd, scrollToIndex, scrollToItem and scrollToOffset now return Promise<void>.
  • state.positions is no longer part of the public getState() return value; use positionAtIndex(index) and positionByKey(key). getState() also exposes listen, listenToPosition, scrollVelocity and getAverageItemSizes().
  • initialContainerPoolRatio has been removed, as spare container capacity is managed automatically. InitialScrollAnchor has been replaced by ScrollIndexWithOffsetPosition.

The guide also includes a migration checklist summarizing these steps. The package installs with:

npm install @legendapp/list

Source: legendapp.com