Skip to content

cats-oss/use-intersection

Repository files navigation

use-intersection

npm CircleCI

React Hooks for IntersectionObserver.

🐢 See Storybook.

Installation

$ yarn add use-intersection

Usage

Basic

This is the simplest example.

import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';

const Component: React.FC = () => {
  const target = useRef<HTMLDivElement>(null);
  const intersecting = useIntersection(target);

  return <div ref={target}>{intersecting ? 'visible' : 'invisible'}</div>;
};

Custom Root Element

This is an example of using scrollable elements other than Viewport.

import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';

const Component: React.FC = () => {
  const root = useRef<HTMLDivElement>(null);
  const target = useRef<HTMLDivElement>(null);
  const intersecting = useIntersection(target, {
    root,
    rootMargin: '100px',
  });

  return (
    <div style={{ overflow: 'hidden auto', height: 300 }}>
      {/* ... */}
      <div ref={target}>{intersecting ? 'visible' : 'invisible'}</div>
      {/* ... */}
    </div>
  );
};

Lazy Image

This is an example of an Image component that delays loading.

import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';

const LazyImage: React.FC<React.ComponentProps<'img'>> = (props) => {
  const target = useRef<HTMLSpanElement>(null);
  const intersected = useIntersection(target, {
    rootMargin: '250px',
    once: true,
  });

  return <span ref={target}>{intersected && <img {...props} />}</span>;
};

Browser support

Supports modern web browser.

If your browser does not support IntersectionObserver, we recommend using Polyfill.

npm package

$ yarn add intersection-observer

https://www.npmjs.com/package/intersection-observer

CDN

<script src="https://polyfill-fastly.io/v3/polyfill.min.js?features=IntersectionObserverEntry%2CIntersectionObserver"></script>

https://polyfill-fastly.io/v3/

API

The following resources will help you.


useIntersection

useIntersection returns a flag whether the target intersects.

const useIntersection = (
  target: React.RefObject<Element> | Element | null,
  options: IntersectionOptions = {},
  callback?: IntersectionChangeHandler,
) => boolean;

options: IntersectionOptions

type IntersectionOptions = {
  root?: React.RefObject<Element>;
  rootMargin?: string;
  threshold?: number | number[];
  once?: boolean;
  defaultIntersecting?: boolean;
};

callback: IntersectionChangeHandler

type IntersectionChangeHandler = (entry: IntersectionObserverEntry) => void;

CHANGELOG

See CHANGELOG.md.

Contributing

We are always welcoming your contribution πŸ‘

  1. Fork (https://github.com/cats-oss/use-intersection) πŸŽ‰
  2. Create a feature branch β˜•
  3. Run test suite with the $ yarn test command and confirm that it passes ⚑
  4. Commit your changes πŸ“
  5. Rebase your local changes against the master branch πŸ’‘
  6. Create new Pull Request πŸ’Œ

Bugs, feature requests and comments are more than welcome in the issues.

Development scripts

yarn storybook

Run Storybook.

$ yarn storybook

yarn test

Run Unit test with Jest.

$ yarn test

yarn lint

Run lint with ESLint.

$ yarn lint

yarn format

Run formatting with ESLint (--fix) and Prettier.

$ yarn format

License

MIT Β© Cyberagent, Inc