This library was developed as a replacement for the browser's IntersectionObserver API.
It provides item tracking functionality for lists that offer an onViewableItemsChanged callback with the type ({viewableItems: ViewToken[]}) => void and a renderItem property with the type ({item: ItemT, index: number}) => React.ReactElement.
npm install react-native-observable-listYou can use the useInViewPort hook anywhere within the item to register an event handler that will trigger when the item enters or leaves the viewport.
The optional deps array of useInViewPort and useIsFirst does not work like useEffect dependencies. When deps change, the callback is not executed but re-registered: the registered callback is simply replaced with a new one that captures the latest values, and execution is still driven by viewport enter/leave events.
The newly created component with observe will have an observeEnabled (optional, default is true) property.
$$enabledis deprecated. It still works as a fallback whenobserveEnabledis not set, but it will be removed in a future major release.
import { FlatList } from 'react-native';
import { observe, useInViewPort } from 'react-native-observable-list';
import { useIsFocused } from '@react-navigation/native';
const ObservableFlatList = observe(FlatList);
const data = Array.from({ length: 100 });
const Item = ({ id }) => {
// The callback is re-registered whenever deps change.
// clean is executed when an item leaves the viewport. (not unmount)
useInViewPort(() => {
console.log(`id: ${id} is visible.`);
return () => {
console.log(`id: ${id} has been hidden.`);
};
}, []);
return <View style={{ height: 100 }} />;
};
const App = () => {
const isFocused = useIsFocused();
return (
<ObservableFlatList
observeEnabled={isFocused} // if you need
data={data}
renderItem={() => <Item />}
/>
);
};Observer is a component wrapper around useInViewPort for places where you cannot call the hook directly. It renders its single child as-is (enforced with React.Children.only) and takes two callbacks.
onInViewPort: () => T(required): runs when the item enters the viewport.onOutOfViewPort?: (value: T) => void(optional): runs when the item leaves the viewport, receiving the value returned byonInViewPortin the same enter/leave cycle. The genericTlinks the two signatures — e.g. withonInViewPort={() => Date.now()}, the argument ofonOutOfViewPortis inferred asnumber.
import { FlatList, View } from 'react-native';
import { observe, Observer } from 'react-native-observable-list';
const ObservableFlatList = observe(FlatList);
const data = Array.from({ length: 100 }, (_, i) => i);
const App = () => {
return (
<ObservableFlatList
data={data}
renderItem={({ item }) => (
<Observer
onInViewPort={() => Date.now()} // runs on enter
onOutOfViewPort={(enteredAt) => {
// runs on leave with the value returned on enter
console.log(`${item} was visible for ${Date.now() - enteredAt}ms`);
}}
>
<View style={{ height: 100 }} />
</Observer>
)}
/>
);
};Internally, Observer keeps both callbacks in refs and registers a single stable wrapper with useInViewPort(wrapper, []). Because deps is fixed to [], changing the callback prop identities on re-render never re-registers (replaces) the callback — execution timing is decided by viewport enter/leave events only, and the latest callbacks are always the ones executed. The value returned on enter is captured per cycle and handed to the latest onOutOfViewPort on leave.
So while the deps of useInViewPort work differently from useEffect (replace on change, never execute), Observer goes one step further: there are no deps to manage at all.
IsFirst is a component wrapper around useIsFirst for places where you cannot call the hook directly. It renders its single child as-is (enforced with React.Children.only) and takes one callback.
onFirst: () => void(required): runs when the item becomes the first visible item.
import { FlatList, View } from 'react-native';
import { observe, IsFirst } from 'react-native-observable-list';
const ObservableFlatList = observe(FlatList);
const data = ['blue', 'yellow', 'green', 'orange'];
const App = () => {
return (
<ObservableFlatList
data={data}
renderItem={({ item: color }) => (
<IsFirst
onFirst={() => {
console.log(`${color} is now the first visible item.`);
}}
>
<View style={{ backgroundColor: color, height: 500 }} />
</IsFirst>
)}
/>
);
};Internally, IsFirst keeps the callback in a ref and registers a single stable wrapper with useIsFirst(wrapper, []), the same structure as Observer: changing the callback prop identity on re-render never re-registers anything, and the latest callback is always the one executed on first-item transitions.
install dependencies
yarn install
run on expo android
yarn example android
run on expo ios
yarn example ios
Example1 (Nesting)
It supports both reverse and forward nesting.
It can also be used with containers that do not have the onViewableItemsChanged and renderItem props.
import { observe } from 'react-native-observable-list';
import Carousel, {
type TCarouselProps,
} from 'react-native-reanimated-carousel';
function ViewableCarousel<T>(
props: TCarouselProps<T> & {
onViewableItemsChanged?: ({
changed,
viewableItems,
}: {
changed: ViewToken[];
viewableItems: ViewToken[];
}) => void;
}
) {
return (
<Carousel
{...props}
onProgressChange={(offsetProgress: number, absoluteProgress: number) => {
const index = Math.floor(absoluteProgress);
const item = props.data[index];
props.onViewableItemsChanged?.({
changed: [],
viewableItems: [{ item, index, isViewable: true, key: undefined }],
});
props.onProgressChange?.(offsetProgress, absoluteProgress);
}}
/>
);
}
const ObservableCarousel = observe(ViewableCarousel);Example3 (FlashList)
It can also be used with FlashList, which offers a similar interface to FlatList.
In this case, you have to use a key in the internal list to prevent recycling.
import { observe } from 'react-native-observable-list';
import { FlashList } from '@shopify/flash-list';
const ObservableFlatList = observe(FlashList);
const Example3 = () => {
return (
<ObservableFlatList
// ...
renderItem={({ index: outerIndex }) => {
return (
<ObservableFlatList
key={`inner-list-${outerIndex}`} // do not recycle !!
// ...
/>
);
}}
/>
);
};Example4 (Detect First Item)
The callback function registered with the useIsFirst hook is triggered when the first item changes.
import { useState } from 'react';
import { FlatList, View } from 'react-native';
import { observe, useIsFirst } from 'react-native-observable-list';
const ObservableFlatList = observe(FlatList);
const Item = ({
color,
onFirst,
height = 500,
}: {
color: string;
onFirst: () => void;
height?: number;
}) => {
useIsFirst(() => {
onFirst();
}, [color]);
return <View style={{ backgroundColor: color, height }} />;
};
const data = ['blue', 'yellow', 'green', 'orange'];
const Example4 = () => {
const [first, setFirst] = useState<string | undefined>(undefined);
return (
<ObservableFlatList
data={data}
renderItem={({ item: color }) => {
return (
<Item
color={color}
onFirst={() => {
setFirst(color);
}}
/>
);
}}
/>
);
};If a keyExtractor is provided, its return value is used as the key to store visibility status. It is called with (item, index), the same contract as FlatList.
Without a keyExtractor, keys are extracted with the same rules as FlatList's default key extractor: item.key if present, then item.id, then String(index).
FlatList considers an item component as non-existent if it doesn't occupy space (e.g., <View />), even if the component is within the viewport.
On the other hand, FlashList considers an item as existent as long as it is within the viewport, even if it doesn't occupy space.
const Item = ({ id }: any) => {
useInViewPort(() => {
console.log(`${id} mount !!`);
return () => {
console.log(`${id} unmount !!`); // executed on FlatList
};
});
const [hide, setHide] = useState(false);
useEffect(() => {
setTimeout(() => {
setHide(true);
}, 1000);
}, []);
if (hide) return <View />;
return <View style={{ width: 10, height: 10 }} />;
};Therefore, the cleanup function of useInViewPort was not designed to run when unmounted, but depending on the situation, it may still run during unmounting.
I was unable to cast the input type directly to add the observeEnabled property.
Despite trying various casting methods, both FlatList and FlashList could not infer the item type.
As a result, I had to override the property that uses the item type in props.
Therefore, while there should be no issue when wrapping FlatList, if you wrap a custom component (e.g., Example2), newly added properties like getItemLayout, CellRendererComponent, and getItemType might be recognized by the newly created component.
You may need to check if the original component has the same properties and override them as needed, like in Example2.
I will define the component wrapped with observe as Observable List.
All lists up to the root of the item where the useInViewPort hook is used must be Observable Lists.
If the nested list is not an Observable List, its items will not be properly tracked.
In the example below, when the inner FlatList becomes visible on the screen, it is considered that all of its items are being in the viewport.
const Example1 = () => {
return (
<ObservableFlatList
style={styles.container}
data={outerData}
ListHeaderComponent={<View style={styles.header} />}
renderItem={({ index: outerIndex }) => {
if (outerIndex % 10) return <TrackableItem label={`${outerIndex}`} />;
return (
<FlatList // not allowed
data={innerData}
horizontal
renderItem={({ index: innerIndex }) => {
return (
<TrackableItem
width={100}
label={`${outerIndex}-${innerIndex}`}
/>
);
}}
/>
);
}}
/>
);
};FlatList excludes items that start being managed as Sticky Headers from viewableItems.
Because of this, even if an item with the sticky property is visible on the screen, it may be perceived as gone.
FlashList duplicates sticky items and overlaps them.
Because of this, items may appear twice and be perceived as disappearing.
In FlashList, sticky items are duplicated and overlaid with an absolute position.
This may cause state changes to not function properly. As a result, Example 4 will not work when using FlashList.
Additionally, since sticky headers in FlashList are treated as items outside of the list, any item being tracked as the first header will be considered "first" once it scrolls up by the height of the sticky header.
MIT
Made with create-react-native-library