@thibault.sh/hooks/dist/useIntersectionObserver.d.mts

A comprehensive collection of React hooks for browser storage, UI interactions, and more

import { RefObject } from 'react';

interface IntersectionOptions extends IntersectionObserverInit {
    freezeOnceVisible?: boolean;
}
/**
 * Hook that tracks when an element enters or leaves the viewport using the Intersection Observer API.
 *
 * Useful for implementing lazy loading, infinite scrolling, animations on scroll,
 * or tracking visibility of elements for analytics purposes.
 *
 * @param elementRef - React ref object pointing to the target element to observe
 * @param options - Configuration options for the intersection observer:
 *   - `threshold`: Number or array defining at what percentage of visibility the callback should trigger (0-1)
 *   - `root`: Element used as viewport for checking visibility (defaults to browser viewport)
 *   - `rootMargin`: Margin around the root element (CSS-like syntax, e.g., "10px 20px")
 *   - `freezeOnceVisible`: If true, stops observing once element becomes visible (useful for one-time animations)
 *
 * @returns IntersectionObserverEntry object containing visibility information, or null if element not found
 *
 * @example
 * ```tsx
 * function LazyImage({ src, alt }: { src: string; alt: string }) {
 *   const imgRef = useRef<HTMLImageElement>(null);
 *   const entry = useIntersectionObserver(imgRef, {
 *     threshold: 0.1,
 *     freezeOnceVisible: true
 *   });
 *
 *   const isVisible = entry?.isIntersecting;
 *
 *   return (
 *     <img
 *       ref={imgRef}
 *       src={isVisible ? src : undefined}
 *       alt={alt}
 *       style={{ opacity: isVisible ? 1 : 0 }}
 *     />
 *   );
 * }
 * ```
 *
 * @see https://thibault.sh/hooks/use-intersection-observer
 */
declare function useIntersectionObserver<T extends HTMLElement>(elementRef: RefObject<T | null> | null, { threshold, root, rootMargin, freezeOnceVisible }?: IntersectionOptions): IntersectionObserverEntry | null;

export { useIntersectionObserver };