https://github.com/ukorvl/react-on-screen

Lightweight typescript library to detect React elements visibility
https://github.com/ukorvl/react-on-screen

dom-intersection element-visibility in-viewport intersection-observer onscreen react react-custom-hook react-hooks react-intersection-observer react-on-screen typescript view-tracking viewport viewports visibility visibility-detection

Last synced: 3 months ago
JSON representation

Lightweight typescript library to detect React elements visibility

• Host: GitHub
• URL: https://github.com/ukorvl/react-on-screen
• Owner: ukorvl
• License: mit
• Created: 2022-12-02T22:08:40.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2025-02-22T17:12:02.000Z (about 1 year ago)
• Last Synced: 2025-10-12T05:41:59.963Z (6 months ago)
• Topics: dom-intersection, element-visibility, in-viewport, intersection-observer, onscreen, react, react-custom-hook, react-hooks, react-intersection-observer, react-on-screen, typescript, view-tracking, viewport, viewports, visibility, visibility-detection
• Language: TypeScript
• Homepage:
• Size: 983 KB
• Stars: 3
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

          

  

  

Lightweight typescript library to detect React elements visibility

[![Build](https://github.com/ukorvl/react-on-screen/actions/workflows/build.yaml/badge.svg)](https://github.com/ukorvl/react-on-screen/actions/workflows/build.yaml)

[![Npm version](https://img.shields.io/npm/v/@ukorvl/react-on-screen?logo=npm)](https://www.npmjs.com/package/@ukorvl/react-on-screen)

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

[![Minified size](https://img.shields.io/bundlephobia/min/@ukorvl/react-on-screen)](https://bundlephobia.com/package/@ukorvl/react-on-screen)

## Table of contents

  - [Getting started](#getting-started)

  - [Usage](#usage)

    - [Render props](#render-props)

    - [Hook](#hook)

    - [HOC](#hoc)

    - [Api](#api)

  - [License](#license)

## Getting started

### npm

```bash

$ npm i @ukorvl/react-on-screen

```

### yarn

```bash

yarn add @ukorvl/react-on-screen

```

### CDN

```html

```

The standalone version creates window.ReactOnScreen object with all exports from esm version.

Note, that ```react``` package is not included into standalone version, but is required. Standalone version requires global ```React``` variable to work as expected.

## Usage

This library is using Intersection observer API under the hood, so you may need to polyfill it. More information about Intersection observer API browser support at [caniuse](https://caniuse.com/intersectionobserver).

### Render props

```tsx

import { OnScreen } from '@ukorvl/react-on-screen';

const MyComponent = () => (

  

    {({isOnScreen, ref}) => (

      


        {isOnScreen ? 'On screen!' : 'Not on screen'}

      

    )}

  

)

```


### Hook

```tsx

import useOnScreen from '@ukorvl/react-on-screen';

const MyComponent = () => {

  const ref = useRef(null);

  const {isOnScreen} = useOnScreen({ref});

  return (

    
{isOnScreen ? 'On screen!' : 'Not on screen'}

  )

}

```


### HOC

```tsx

import { WithOnScreen } from '@ukorvl/react-on-screen';

const List = forwardRef(function List({isOnScreen, ...restProps}: ListProps, ref) {

  return (

    


      
Something

        {'...'}

    

  )

})


export const ListWithOnScreen = WithOnScreen(List, {threshold: 0.5, margin: '4rem'});

```

### API

**useOnScreen** hook parameters.

|Name            |Default         |Description        |

|----------------|----------------|-------------------|

|threshold       |0                |Could be a single number from 0 to 1, or array of numbers. If you only want to detect when visibility passes the 50% mark, you can use a value of 0.5. Set 1 to consider visibility only if all element is on the screen. If array of thresholds is provided, visibility detection will be triggered every time visibility passes one of provided thresholds.|

|margin          |undefined        |Could be any valid css margin value. This value serves to grow or shrink each side of the target element's bounding box before computing is it visible or not.|

|once            |false            |Triggers visibility detection only once. Once target element becomes visible, visibility detection will be disabled.|

|initialVisibility |false          |Initial isOnScreen value. Could be useful when working with elements that are on the screen at the first render, and we don't want to wait for InersectionObserver initialization to do some actions.|

**OnScreen** and **WithOnScreen** components have the same api, except ref. **useOnScreen** consumes target element ref as a parameter, but components deal with target element in a different way.

## License

[MIT](http://opensource.org/licenses/MIT)