use-element-in-view
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.3 • Public • Published

    use-element-in-view

    A simple React hook to track whether an element is visible in the viewport with the Intersection Observer. This API provides a native way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport.

    Browser support for the Intersection Observer is incredibly wide, you can view the full list here. However, if you need to support older browsers, you can add a polyfill from here.

    Install

    💡 Note: Since this module uses React Hooks, you'll need to have version >=16.8.0 of react and react-dom installed in your project

    npm install use-element-in-view --save-dev
    # or
    yarn add use-element-in-view --dev

    Quick Start

    import React from 'react';
    import { useElementInView } from 'use-element-in-view';
    
    function App() {
        const { inView, assignRef } = useElementInView();
    
        return <div ref={assignRef}>In View? {inView}</div>;
    }

    Using your own ref.

    import React, { useRef } from 'react';
    import { useElementInView } from 'use-element-in-view';
    
    function App() {
        const ref = useRef<HTMLDivElement>(null);
        const { inView } = useElementInView({ ref });
    
        return <div ref={ref}>In View? {inView}</div>;
    }

    You can view more examples on CodeSandbox (coming soon).

    API

    useElementInView(options)

    function useElementInView<T extends HTMLElement = HTMLElement>(
        options?: IElementInViewOptions<T> = {}
    ): IElementInViewResult<T>;

    Arguments: IElementInViewOptions<T>

    • Note, all arguments are optional. The properties root, rootMargin and threshold are specific to the native Intersection Observer API and are forwarded along, more information can be found here
    Argument Type Default value Description
    ref T | RefObject<T> | null null Pass in your own ref instead of using the ref callback provided. This can be useful if you already have a ref inside your component you want to observe.
    defaultInView boolean false Set the default value for the inView property.
    disconnectOnceVisible boolean false Will disconnect the observer once the observed element has entered the viewport. A use-case for this is for lazy-loading images.
    onChange (entry: IntersectionObserverEntry) => void undefined Provide a callback that receives the full IntersectionObserverEntry as an argument that fires on each change of element intersection.
    root Element | null null The Element or Document whose bounds are used as the bounding box when testing for intersection. If no root value was passed to the constructor or its value is null, the top-level document's viewport is used
    rootMargin string '0px' A string which specifies a set of offsets to add to the root's bounding box when calculating intersections, effectively shrinking or growing the root for calculation purposes. The syntax is approximately the same as that for the CSS margin property. The default is "0px 0px 0px 0px".
    threshold number | number[] 0 A list of thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of an observed target. Notifications for a target are generated when any of the thresholds are crossed for that target. If no value was passed to the constructor, 0 is used.

    Returns: IElementInViewResult<T>

    Argument Type Description
    inView boolean Value representing if the observed element is visible in the viewport or not.
    entry IntersectionObserverEntry | undefined The full entry (IntersectionObserverEntry) returned from the Intersection Observer callback when invoked.
    assignRef RefCallback<T> A callback ref to be assigned to your element. Note, if you do not pass in your own ref, this must be added to the element you wish to observe.
    disconnect () => void Function that will disconnect the current observer instance shall you need to trigger this yourself.

    Contributing

    You can report bugs and issues here.

    Pull-requests are more than welcome if you feel like you can improve or fix something 💥

    License

    MIT

    Install

    npm i use-element-in-view

    DownloadsWeekly Downloads

    9

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    57.7 kB

    Total Files

    13

    Last publish

    Collaborators

    • joshuaaron