react-inview-callback

Custom React hook that will detect an element entry and exit on the viewport using the Intersection Observer API, check the browser support on canisue website, for older browsers support I recommend the use of polyfill as IntersectionObserver polyfill.

Usage no npm install needed!

<script type="module">
  import reactInviewCallback from 'https://cdn.skypack.dev/react-inview-callback';
</script>

README

InView Callback a Custom React Hook

npm version https://img.shields.io/librariesio/release/npm/react-inview-callback https://img.shields.io/github/issues-raw/mario-duarte/react-inView https://img.shields.io/snyk/vulnerabilities/github/mario-duarte/react-inView

Custom React hook that will detect an element entry and exit on the viewport using the Intersection Observer API, check the browser support on canisue website, for older browsers support I recommend the use of polyfill as IntersectionObserver polyfill.

View it in action on this demo page!

Buy me a coffee to keep me going!

Why?

As a long user of jQuery I have developed many plugins over the years that have helped me developing solutions faster and more reliably. As I move and transition to React(♥) I wanted some of these to come along with me on this new journey.

I like my plugins(now components/hooks) to be as flexible as possible and to not get in the way of the styling of the app/site that is been implemented to and this is no different.

Want to come along on this journey and/or have some great ideas on how to improve this Hook? Check out the repo here!

How it works?

Custom Hook that as the Intersection Observer API provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport that will run a custom callback on entry and exit.

How to install

To install this on your project run the following command on your terminal:
npm install react-inview-callback

Alternatively you can also install using yarn:
yarn add react-inview-callback

How to Use

Import the custom hook in your component:

import useInView from 'react-inview-callback';

And now you can start using the hook on your component, the hook will take in 4 parameters. useInView(elmRef, options, onEntry, onExit);

The elmRef is the reference to the DOM element you want to observe in the viewport and you can set this using the useRef react hook, here is simple example of this.

  import {useRef} from 'react';
  import useInView from 'react-inview-callback';

  export default function myComponent() {
    const myref = useRef(null);

    return(
      <div className="my-component" ref={myref}>
      </div>
    );
  }

You can then call the custom hook on you reference element like so:

  useInView(myref, options, onEntry, onExit);

The options parameter is an object that you can pass to the hook to control circumstances under which the observer's will use the callback in a similar fashion to the option object in the Intersection Observer API.

  const options = {
    root : 'root',
    rootMargin : '0px',
    threshold : 1
  }

root :
The element that is used as the viewport for checking visibility of the target. Must be an ancestor of the reference element. Defaults to the document body if not specified or if null.

rootMargin:
Margin around the root element, this can take values in a similar way to css using a variety of units such as pixel and percentage. You can also set this to a negative number and serves to modify the root bounding box before computing intersections.

threshold:
This is a number between 1 and 0 that defines when the callbacks are called, for example, if you want to detect when 50% of the element is visible in the viewport you you would set it to 0.5.
If you want your callbacks to run at multiple steps, for example, when the element is 50% visible and then again when it is 100% visible you can pass an array of number like [0.5,1].

The onEntry and onExit parameters are callback functions that are executed once the reference element enters and exits the viewport, when the hook executes these callbacks it returns to them the Intersection Observer entry object that you can use to get the boundingClientRect, intersectionRatio, intersectionRect, isIntersecting, rootBounds, target, time properties.

You can read more about these on the Intersection Observer API webpage.

So all together now our example would look like:

  import {useRef} from 'react';
  import useInView from 'react-inview-callback';

  export default function myComponent() {
    const myref = useRef(null);

    function onEntry(entry) {
      console.log('Element has entered the view port');
      myref.current.classList.add('visible');
      setVisibility(true);
    }

    function onExit(entry) {
      console.log('Element has exited the view port');
      myref.current.classList.remove('visible');
      setVisibility(false);
    }

    const options = {
      root : 'root',
      rootMargin : '0px',
      threshold : 1
    }

    useInView(myref, options, onEntry, onExit);

    return(
      <div className="my-component" ref={myref}>
      </div>
    );
  }

Bugs and issues

Please report all bugs and issues here.