react-native-lazy-scrollview

Lazy Scrollers for React Native.

---

Provides an api to react to allow child components of ScrollView or FlatList to easily manage their visibility states on their own, instead of at a list level. This is done by measuring children on the UI thread and only firing back to JS when a defined threshold has been passed.

Installation

yarn add react-native-lazy-scrollview

This library requires reanimated. Follow their installation instructions.

Getting Started

1. Swap out ScrollView or Flatlist for LazyScrollView or LazyFlatlist.
2. Wrap any child of the list that you'd like to react to visibility in LazyChild.
3. Define LazyChild's callbacks. entering/exiting callbacks fire when the child passes the parent list's threshold when compared to its edge (default is 0, meaning top and bottom of the list). visibility callbacks fire when the child has its percentVisibleThreshold met (defaults to 1, or 100%). You can add a minimumVisibilityMs value to delay/prevent firing a visbility callback until it has been visible for a certain amount of time.

Notes

• If a LazyChild does not have a LazyScrollview/LazyFlatlist ancestor, it will fire its onEnterThresholdPass and onVisibilityEnter on mount.
• If a corresponding 'exit' callback is not provided for an 'enter' callback, after the 'enter' callback fires, measuring stops for that callback.
• scrollEventThrottle defaults to 16.

API

LazyScrollView

Props

Extends ScrollView props, omitting onLayout and ref (see below).

Name	Type	Required	Description
offset	number	No	How far above or below the bottom of the ScrollView the threshold trigger is. Negative = above, positive = below. Default: 0 (bottom of ScrollView).
ref	MutableRefObject<LazyScrollViewMethods>	No	Ref to the LazyScrollView. Exposes scrollTo, scrollToStart, and scrollToEnd methods.
debug	boolean	No	When true, logs measurement data for debugging. Logs are disabled in production.

Methods

Method	Type	Description
scrollTo	Maps to ScrollView scrollTo	Scrolls to a specific x/y offset.
scrollToStart	(options?: { animated: boolean }): void	Scrolls to the start of the list.
scrollToEnd	(options?: { animated: boolean }): void	Scrolls to the end of the list.

LazyFlatlist

Props

Extends Flatlist props, omitting onLayout and ref (see below).

Name	Type	Required	Description
offset	number	No	How far above or below the bottom of the FlatList the threshold trigger is. Negative = above, positive = below. Default: 0 (bottom of FlatList).
ref	MutableRefObject<LazyFlatListMethods | null>	No	Ref to the LazyFlatList. Exposes scrollToStart, scrollToEnd, scrollToIndex, scrollToOffset, and scrollToItem methods.
debug	boolean	No	When true, logs measurement data for debugging. Logs are disabled in production.

Methods

Method	Type	Description
scrollToStart	(options?: { animated: boolean }): void	Scrolls to the start (top/left) of the list.
scrollToEnd	(options?: { animated: boolean }): void	Scrolls to the end (bottom/right) of the list.
scrollToIndex	Maps to Flatlist scrollToIndex	Scrolls to the item at the given index.
scrollToOffset	Maps to Flatlist scrollToOffset	Scrolls to a specific offset.
scrollToItem	Maps to Flatlist scrollToItem	Scrolls to a specific item.

LazyChild

Props

Name	Type	Required	Description
onEnterThresholdPass	() => void	No	Fires when the child passes the scroll offset after being offscreen. Only fires once and stops measuring if onExitThresholdPass is not provided.
onExitThresholdPass	() => void	No	Fires when the child passes the scroll offset after being onscreen. Will not fire if onEnterThresholdPass has not fired.
onVisibilityEnter	() => void	No	Fires when the child’s viewable area exceeds the percentVisibleThreshold. Only fires once and stops measuring if onVisibilityExit is not provided.
onVisibilityExit	() => void	No	Fires when the child’s viewable area goes under the percentVisibleThreshold after being above it. Will not fire if onVisibilityEnter has not fired.
children	React.ReactNode	Yes	The child component(s) to wrap.
percentVisibleThreshold	number	No	Fraction of the child that must be visible before onVisibilityEnter fires. Example: 0.5 = 50% visible. Default: 1.0.
minimumVisibilityMs	number	No	Minimum time (ms) the child must remain visible before onVisibilityEnter fires. If undefined, fires immediately.
debug	boolean	No	When true, logs measurement data for debugging. Logs are disabled in production.

Usage Examples

// MyCoolHomeScreen.tsx
import { LazyScrollView } from 'react-native-lazy-scrollview';
import {
  CoolComponentA,
  CoolComponentB,
  CoolComponentC,
  PriceMasterVideo,
  ScrollToTopButton,
} from './components';

export function MyCoolHomeScreen() {
  const ref = useRef < LazyScrollViewMethods > null;

  return (
    // Trigger entering/exiting callbacks when child is 300 pixels outside of scrollview's bounds
    <LazyScrollView offset={300} showsVerticalScrollIndicator={false}>
      <CoolComponentA />
      <PriceMasterVideo />
      <CoolComponentB />
      <CoolComponentC />
      <ScrollToTopButton
        onPress={() => ref.current?.scrollToStart({ animated: true })}
      />
    </LazyScrollView>
  );
}

// CoolComponentC.tsx
import { View } from 'react-native';
import { LazyChild } from 'react-native-lazy-scrollview';
import { ContentView, SkeletonLoader } from './components';

export function CoolComponentC() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  const onEnterThresholdPass = useCallback(async () => {
    try {
      const fetchedData = await someExpensiveApiCall();
      setData(fetchedData);
      setLoading(false);
    } catch (e) {
      setLoading(false);
    }
  }, []);

  // Fired when LazyChild has 75% visibility for over 250 ms
  const onVisibilityEnter = useCallback(async () => {
    analyticsCall();
  }, []);

  if (!loading && !data) {
    // Trigger has fired and no data :(
    return null;
  }

  return (
    <LazyChild
      onEnterThresholdPass={onEnterThresholdPass}
      onVisibilityEnter={onVisibilityEnter}
      percentVisibleThreshold={0.75}
      minimumVisibilityMs={250}
    >
      {loading ? <SkeletonLoader /> : <ContentView data={data} />}
    </LazyChild>
  );
}

// PriceMasterVideo.tsx
import { View } from 'react-native';
import { LazyChild } from 'react-native-lazy-scrollview';
import { ContentView, SkeletonLoader, VideoPlayer } from './components';

const videoURl = 'https://youtu.be/wfJnni0oBPE?si=kRdIUcq4l5dfGfqV';

export function PriceMasterVideo() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [paused, setPaused] = useState(true);

  const onEnterThresholdPass = useCallback(async () => {
    setLoading(false);
  }, []);

  // Fired when LazyChild has 25% visibility
  const onVisibilityEnter = useCallback(async () => {
    analyticsCall();
    setPaused(false);
  }, []);

  // Fired when LazyChild is less that 25% visible after being visible
  const onVisibilityExit = useCallback(async () => {
    setPaused(true);
  }, []);

  return (
    <LazyChild
      onEnterThresholdPass={onEnterThresholdPass}
      onVisibilityEnter={onVisibilityEnter}
      onVisibilityExit={onVisibilityExit}
      percentVisibleThreshold={0.25}
    >
      {loading ? (
        <SkeletonLoader />
      ) : (
        <VideoPlayer paused={paused} videoUrl={videoUrl} />
      )}
    </LazyChild>
  );
}

Example App

To run the example app, clone the repo

cd example
yarn install

yarn ios
# or
yarn android

License

MIT

---

Made with create-react-native-library