shadowlist

0.4.19 • Public • Published

shadowlist [alpha release]

ShadowList is a new alternative to FlatList for React Native, created to address common performance issues and enhance the UX when dealing with large lists of data. It invokes Yoga for precise layout measurements of Shadow Nodes and constructs a Fenwick Tree with layout metrics for efficient offset calculations. By virtualizing children and rendering only items within the visible area, ShadowList ensures optimal performance. It's built on Fabric and works with React Native version 0.75 and newer.

Out of box comparison to FlatList

Feature ShadowList FlatList / FlashList
60 FPS Scrolling
No Estimated Size required
No Content Flashing
No Sidebar Indicator Jump
Native Bidirectional List
Instant initialScrollIndex
Instant initialScrollIndex
Nested ShadowList (ScrollView)
Natively Inverted List Support
Smooth Scrolling

Scroll Performance

Number of Items ShadowList FlatList FlashList
100 (text only) 156mb memory - 60fps 195mb (38-43fps) 180mb (56fps)*
1000 (text only) 187mb memory - 60fps 200mb (33-38fps) 180mb (56fps)*

*FlashList is unreliable and completely breaks when scrolling, resulting in unrealistic metrics.
Given measurements show memory usage and FPS on fully loaded content, see demo here and implementation details here.

Note on Performance Considerations

ShadowList initiates ShadowNode creation for each child. This process can be slower when rendering a large number of items at once, which may impact performance compared to purely JS-based solutions. However, once the children are measured, it performs real-time virtualization ensuring smooth, flicker-free scrolling.

One temporary way to mitigate this is by implementing list pagination until the following problem is addressed.

Installation

  • CLI: Add the package to your project via yarn add shadowlist and run pod install in the ios directory.
  • Expo: Add the package to your project via npx expo install shadowlist and run npx expo prebuild in the root directory.

Usage

import {Shadowlist} from 'shadowlist';

<Shadowlist
  contentContainerStyle={styles.container}
  ref={shadowListContainerRef}
  data={data}
  ListHeaderComponent={ListHeaderComponent}
  ListHeaderComponentStyle={styles.ListHeaderComponentStyle}
  ListFooterComponent={ListFooterComponent}
  ListHeaderComponentStyle={styles.ListFooterComponentStyle}
  ListEmptyComponent={ListEmptyComponent}
  ListEmptyComponentStyle={styles.ListFooterComponentStyle}
  renderItem={({ item, index }) => (
    <CustomComponent item={item} index={index} />
  )}
/>

API

Prop Type Required Description
data Array Required An array of data to be rendered in the list.
keyExtractor Function Required Used to extract a unique key for a given item at the specified index.
contentContainerStyle ViewStyle Optional These styles will be applied to the scroll view content container which wraps all of the child views.
ListHeaderComponent React component Optional A custom component to render at the top of the list.
ListHeaderComponentStyle ViewStyle Optional Styling for internal View for ListHeaderComponent
ListFooterComponent React component Optional A custom component to render at the bottom of the list.
ListFooterComponentStyle ViewStyle Optional Styling for internal View for ListFooterComponent
ListEmptyComponent React component Optional A custom component to render when the list is empty.
ListEmptyComponentStyle ViewStyle Optional Styling for internal View for ListEmptyComponent
renderItem Function Required A function to render each item in the list. It receives an object with item and index properties.
initialScrollIndex Number Optional The initial index of the item to scroll to when the list mounts.
inverted Boolean Optional If true, the list will be rendered in an inverted order.
horizontal Boolean Optional If true, renders items next to each other horizontally instead of stacked vertically.
onEndReached Function Optional Called when the end of the content is within onEndReachedThreshold.
onEndReachedThreshold Double Optional The threshold (in content length units) at which onEndReached is triggered.
onStartReached Function Optional Called when the start of the content is within onStartReachedThreshold.
onStartReachedThreshold Double Optional The threshold (in content length units) at which onStartReached is triggered.

Methods

Method Type Description
scrollToIndex Function Scrolls the list to the specified index.
scrollToOffset Function Scrolls the list to the specified offset.

License

MIT

Package Sidebar

Install

npm i shadowlist

Weekly Downloads

66

Version

0.4.19

License

MIT

Unpacked Size

221 kB

Total Files

146

Last publish

Collaborators

  • azimgd