https://github.com/cats-oss/use-intersection
React Hooks for IntersectionObserver.
https://github.com/cats-oss/use-intersection
intersection-observer react react-hooks reactjs
Last synced: 12 months ago
JSON representation
React Hooks for IntersectionObserver.
- Host: GitHub
- URL: https://github.com/cats-oss/use-intersection
- Owner: cats-oss
- License: mit
- Created: 2019-03-22T12:48:43.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-22T18:11:18.000Z (about 1 year ago)
- Last Synced: 2025-04-02T13:04:16.734Z (about 1 year ago)
- Topics: intersection-observer, react, react-hooks, reactjs
- Language: TypeScript
- Homepage: https://cats-oss.github.io/use-intersection/
- Size: 1.46 MB
- Stars: 108
- Watchers: 1
- Forks: 5
- Open Issues: 63
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# use-intersection
[](https://www.npmjs.com/package/use-intersection)
[](https://circleci.com/gh/cats-oss/use-intersection)
> [React Hooks](https://reactjs.org/docs/hooks-intro.html) for [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
:dog: See [Storybook](https://cats-oss.github.io/use-intersection/).
## Installation
```bash
$ yarn add use-intersection
```
## Usage
### Basic
This is the simplest example.
```typescript
import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';
const Component: React.FC = () => {
const target = useRef(null);
const intersecting = useIntersection(target);
return
{intersecting ? 'visible' : 'invisible'};
};
```
### Custom Root Element
This is an example of using scrollable elements other than Viewport.
```typescript
import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';
const Component: React.FC = () => {
const root = useRef(null);
const target = useRef(null);
const intersecting = useIntersection(target, {
root,
rootMargin: '100px',
});
return (
{/* ... */}
{intersecting ? 'visible' : 'invisible'}
{/* ... */}
);
};
```
### Lazy Image
This is an example of an Image component that delays loading.
```typescript
import React, { useRef } from 'react';
import { useIntersection } from 'use-intersection';
const LazyImage: React.FC> = (props) => {
const target = useRef(null);
const intersected = useIntersection(target, {
rootMargin: '250px',
once: true,
});
return {intersected && ![]()
};
};
```
## Browser support
Supports modern web browser.
If your browser does not support `IntersectionObserver`, we recommend using Polyfill.
### npm package
```bash
$ yarn add intersection-observer
```
> https://www.npmjs.com/package/intersection-observer
### CDN
```html
```
> https://polyfill-fastly.io/v3/
## API
The following resources will help you.
- [React Hooks](https://reactjs.org/docs/hooks-intro.html)
- [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
---
### `useIntersection`
`useIntersection` returns a flag whether the target intersects.
```typescript
const useIntersection = (
target: React.RefObject | Element | null,
options: IntersectionOptions = {},
callback?: IntersectionChangeHandler,
) => boolean;
```
### `options: IntersectionOptions`
```typescript
type IntersectionOptions = {
root?: React.RefObject;
rootMargin?: string;
threshold?: number | number[];
once?: boolean;
defaultIntersecting?: boolean;
};
```
### `callback: IntersectionChangeHandler`
```typescript
type IntersectionChangeHandler = (entry: IntersectionObserverEntry) => void;
```
## CHANGELOG
See [CHANGELOG.md](./CHANGELOG.md).
## Contributing
We are always welcoming your contribution :clap:
1. Fork (https://github.com/cats-oss/use-intersection) :tada:
1. Create a feature branch :coffee:
1. Run test suite with the `$ yarn test` command and confirm that it passes :zap:
1. Commit your changes :memo:
1. Rebase your local changes against the `master` branch :bulb:
1. Create new Pull Request :love_letter:
Bugs, feature requests and comments are more than welcome in the [issues](https://github.com/cats-oss/use-intersection/issues).
### Development scripts
#### `yarn storybook`
Run Storybook.
```bash
$ yarn storybook
```
#### `yarn test`
Run Unit test with Jest.
```bash
$ yarn test
```
#### `yarn lint`
Run lint with ESLint.
```bash
$ yarn lint
```
#### `yarn format`
Run formatting with ESLint (`--fix`) and Prettier.
```bash
$ yarn format
```
## License
[MIT © Cyberagent, Inc](./LICENSE)