Skip to content

An easy-to-use React hook that tells you whether a component/element is visible on the viewport currently, and if yes, how much of it is visible.

Notifications You must be signed in to change notification settings

captain-woof/react-intersection-revealer

Repository files navigation

react-intersection-revealer

GitHub search hit counter npm bundle size npm NPM npm

Think react-intersection-observer, but with more features.

Introduction

react-intersection-revealer is a easy-to-use React hook that tells you whether a component/element is visible on the viewport currently, and if yes, how much of it is visible. The stats get updated when a relevant event occurs.

Install

Installing is easy. Do it like any other package.

npm install --save react-intersection-revealer

Quick Start

This example below is enough to get you started on how to use react-intersection-revealer.

import React, {useRef} from 'react'
import {useIntersectionRevealer} from 'react-intersection-revealer'

export default function YourAwesomeComponent(){
  const ref = useRef()
  const {heightVisible} = useIntersectionRevealer(ref)

  return(
    <>
      <div className="need-to-track" ref={ref}>...</div>
      <p>{`${heightVisible}px (height) of the tracked element is on screen`}</p>
    </>
  )
}

Here's a demo to show react-intersection-revealer's capabilities.

Usage

The useIntersectionRevealer hook provides you with 13 states that hold stats of the target element:

  • inView (Boolean): True if the element is visible, even if only partially. False otherwise.
  • visibleFractionX (Decimal): Fraction of the element's width which is visible; range: [0,1].
  • visibleFractionY (Decimal): Fraction of the element's height which is visible; range: [0,1].
  • height (Decimal): The element's height, in pixels.
  • width (Decimal): The element's width, in pixels.
  • heightVisible (Decimal): The width (pixels) of the element's height which is visible.
  • widthVisible (Decimal): The width (pixels) of the element's width which is visible.
  • x (Decimal): The x coordinate (pixels) of the element from origin where it's rendered.
  • y (Decimal): The y coordinate (pixels) of the element from origin where it's rendered.
  • scrollX (Decimal): The amount of the element that was scrolled passed by, along x-axis.
  • scrollXProgress (Decimal): The fraction of the amount of the element that was scrolled passed by, along x-axis; range: [0,1].
  • scrollY (Decimal): The amount of the element that was scrolled passed by, along y-axis.
  • scrollYProgress (Decimal): The fraction of the amount of the element that was scrolled passed by, along y-axis; range: [0,1].

These stats get updated on any of these events:

  • Viewport resize (window - onresize)
  • Page scroll (window - onscroll)
  • Parent element scroll (parentElement - onscroll)
  • Target element's transition-end (targetElement - ontransitionend)
  • Parent element's transition-end (parentElement - ontransitionend)

The hook requires a reference to the element to be tracked. Use the useRef hook (from React), get a reference, and pass it to both the useIntersectionRevealer hook and the element/component you want to track.

That's all you need to do.

Take a look at the demo site, and its source code to get an idea.

License

MIT © captain-woof

Author

Sohail Saha (aka CaptainWoof)

Buy me a coffee

Please consider supporting me if you find this package useful in your work.