@ukorvl/react-on-screen

Lightweight typescript library to detect React elements visibility


Table of contents

- Getting started
- Usage
- Render props
- Hook
- HOC
- Api
- License

Getting started

$3

``bash
$ npm i @ukorvl/react-on-screen
`

$3

`bash
yarn add @ukorvl/react-on-screen
`

$3

`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.

$3


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

const MyComponent = () => (

{({isOnScreen, ref}) => (

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

)}

)
`

$3

`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'}

)
}
`

$3

`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'});
``

$3

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