@zenithui/utils/dist/hooks/use-intersection-observer.d.ts

A collection of utility functions and hooks to simplify development in the ZenithUI ecosystem.

/** Represents the options for configuring the Intersection Observer. */
type UseIntersectionObserverOptions = {
    /**
     * The element that is used as the viewport for checking visibility of the target.
     * @default null
     */
    root?: Element | Document | null;
    /**
     * A margin around the root.
     * @default '0%'
     */
    rootMargin?: string;
    /**
     * A threshold indicating the percentage of the target's visibility needed to trigger the callback.
     * @default 0
     */
    threshold?: number | number[];
    /**
     * If true, freezes the intersection state once the element becomes visible.
     * @default false
     */
    freezeOnceVisible?: boolean;
    /**
     * A callback function to be invoked when the intersection state changes.
     * @param {boolean} isIntersecting - A boolean indicating if the element is intersecting.
     * @param {IntersectionObserverEntry} entry - The intersection observer Entry.
     * @default undefined
     */
    onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void;
    /**
     * The initial state of the intersection.
     * @default false
     */
    initialIsIntersecting?: boolean;
};
/**
 * The return type of the useIntersectionObserver hook.
 *
 * Supports both tuple and object destructing.
 * @param {(node: Element | null) => void} ref - The ref callback function.
 * @param {boolean} isIntersecting - A boolean indicating if the element is intersecting.
 * @param {IntersectionObserverEntry | undefined} entry - The intersection observer Entry.
 */
type IntersectionReturn = [
    (node?: Element | null) => void,
    boolean,
    IntersectionObserverEntry | undefined
] & {
    ref: (node?: Element | null) => void;
    isIntersecting: boolean;
    entry?: IntersectionObserverEntry;
};
/**
 * Custom hook that tracks the intersection of a DOM element with its containing element or the viewport using the [`Intersection Observer API`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
 * @param {UseIntersectionObserverOptions} options - The options for the Intersection Observer.
 * @returns {IntersectionReturn} The ref callback, a boolean indicating if the element is intersecting, and the intersection observer entry.
 * @example
 * ```tsx
 * // Example 1
 * const [ref, isIntersecting, entry] = useIntersectionObserver({ threshold: 0.5 });
 * ```
 *
 * ```tsx
 * // Example 2
 * const { ref, isIntersecting, entry } = useIntersectionObserver({ threshold: 0.5 });
 * ```
 */
export default function useIntersectionObserver({ threshold, root, rootMargin, freezeOnceVisible, initialIsIntersecting, onChange, }?: UseIntersectionObserverOptions): IntersectionReturn;
export {};