React Visible Observer

React Visible Observer is a React component library based on the Intersection Observer API, designed to monitor when elements enter or leave the viewport (visible area). This library can trigger callback functions when elements become visible or invisible, making it ideal for implementing lazy loading, animation triggering, and other interactive features dependent on element visibility.

简体中文

Installation

You can install this library via npm or yarn:

npm install react-visible-observer

or

yarn add react-visible-observer

Quick Start

1. Monitor a Single Element

importReact,{useRef}from'react';import{useIntersectionObserver}from'react-visible-observer';constMyComponent=()=>{constref=useRef(null);constonVisibilityChange=(isVisible)=>{console.log(`The element is now ${isVisible ? 'visible' : 'hidden'}`);};useIntersectionObserver(ref,onVisibilityChange);return(<divref={ref}style={{height: '100px',backgroundColor: 'blue'}}>
This is a div that will be observed.
</div>);};exportdefaultMyComponent;

2. Monitor a List of Elements, Typically Used for Infinite Scrolling

importReact,{useRef}from'react';import{useIntersectionObserver}from'react-visible-observer';constMyComponent=()=>{constlistRef=useRef([]);constonVisibilityChange=(isVisible,entry)=>{constid=entry.target.id;// 获取元素的IDconsole.log(`${id} 元素现在 ${isVisible ? '可见' : '不可见'}`);};useIntersectionObserver(listRef,onVisibilityChange);return(<div><divref={el=>listRef.current[0]=el}id="item1">Item 1</div><divref={el=>listRef.current[1]=el}id="item2">Item 2</div><divref={el=>listRef.current[2]=el}id="item3">Item 3</div></div>);};exportdefaultMyComponent;

API

useIntersectionObserver(ref, onVisibilityChange, onEntryUpdate, options)

Option	Description	Type	Required	Default
ref	The ref of the DOM element(s) to observe.	React.RefObject or Array[React.RefObject]	Required	None
onVisibilityChange	Callback function called when the observed element goes from invisible to visible or from visible to invisible. Receives two parameters: isVisible (boolean) indicating whether the element is visible, and entry (IntersectionObserverEntry) providing detailed information.	Function	Required	undefined
onEntryUpdate	Callback function called when there is any update, whether the element is visible or not. Receives one parameter: entry (IntersectionObserverEntry).	Function	Optional	undefined
options	Configuration options for IntersectionObserver.	Object	Optional	{ root: null, rootMargin: '0px', threshold: 0.1 }

options Configuration Options

Option	Description	Type	Required	Default
root	The root element of the observer. Default is null, which uses the viewport as the root element.	Element	Optional	null
rootMargin	A string specifying the margins of the root element. Used to increase or decrease the area considered as the viewport.	String	Optional	'0px'
threshold	A number or an array of numbers defining the percentage of target visibility that triggers the callback.	NumberorArray	Optional	0.1

IntersectionObserverEntry Properties

• boundingClientRect: A DOMRectReadOnly object representing the current size and position of the target element's bounding box in viewport coordinates.
• intersectionRatio: A floating-point number indicating the ratio of the intersection area to the target's bounding box or to the root's bounding box, depending on the value of the root property.
• intersectionRect: A DOMRectReadOnly object representing the size and position of the intersection rectangle's intersection area.
• isIntersecting: A Boolean value indicating whether the target element intersects with the root element.
• rootBounds: A DOMRectReadOnly object representing the bounding box of the root element in viewport coordinates. If there is no root element, this value is null.
• target: An Element object representing the target element being observed.
• time: A floating-point number representing the time at which the intersection occurred, in milliseconds.

License

React Visible Observer is released under the MIT License. See the LICENSE file for details.