Gathering detailed insights and metrics for use-is-in-viewport
Installations
npm install use-is-in-viewportDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Min. Node Version
>=10
Node Version
12.16.1
NPM Version
6.13.4
Releases
2
Contributors
4
Unable to fetch Contributors
Languages
2
JavaScript
TypeScript
JavaScript (80.82%)
TypeScript (19.18%)
validate.email 🚀
Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.
Developer
Download Statistics
Total Downloads
2,780,295
Last Day
1,927
Last Week
9,560
Last Month
42,348
Last Year
715,388
GitHub Statistics
MIT License
149 Stars
134 Commits
7 Forks
4 Watchers
8 Branches
4 Contributors
Updated on Jan 27, 2025
Bundle Size
1.92 kB
Minified
921.00 B
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
1.0.9
Package Id
use-is-in-viewport@1.0.9
Unpacked Size
27.66 kB
Size
8.49 kB
File Count
9
NPM Version
6.13.4
Node Version
12.16.1
Total Downloads
Cumulative downloads
Total Downloads
2,780,295
Last Day
24.2%
1,927
Compared to previous day
Last Week
3%
9,560
Compared to previous week
Last Month
-24.2%
42,348
Compared to previous month
Last Year
-13.9%
715,388
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
Peer Dependencies
1
use-is-in-viewport
A react hook to use the IntersectionObserver declaratively in your React app for the purposes of finding out if an element is in a given viewport.
Motivation
I wrote isInViewport for the jQuery world back in the day and while how we build interfaces has changed massively since, the problem isInViewport solves still remains. Since then, the web platform has grown massively and now gives us better primitives to solve this problem in the shape of the Intersection Observer API.
I was looking for a simple way to use the Intersection Observer API in my React app for the purposes of checking if a component is in some viewport. I started off by writing a wrapper around the Intersection Observer API but that still didn't feel right. Its dev ergonomics felt off due to the callback based core interface it shares with the Intersection Observer API.
Then, React Hooks happened! I started
playing around attempting to write a generic useIntersectionObserver hook. I gave up on that idea
in favour of a more directed hook. One which solves a problem that I and many other devs have.
The following guiding principles in combination with the community helped shape the api and serve as a north star for this hook.
Guiding principles
- Solve a real problem
- Test an element in a viewport for visibility
- Make it straightforward to consume the package
- Simple, to the point name
- Easy installation
- Correct peer dependencies to prevent foot-guns
- Tons of docs and examples (in progress)
- Make it easy to address the most likely use-cases
- e.g., "Tell me when an element is visible in the current window viewport", "Tell me when 75% of an element is visible in current window viewport"
- Make it possible to address other use-cases without unnecessary noise
- e.g., "Tell me when an element is visible in my custom viewport", "Let me customize the viewport I want to pass down", "Let me use this with a component that uses React.forwardRef", etc
- Provide as much developer feedback as possible
- made possible by types that ship with the project
- Only solve the actual problem
- e.g., providing a polyfill for Intersection Observer is not this package's job
- Be trustworthy
- All use cases have corresponding integration tests using Cypress (in progress)
With all all major browsers having added support for Intersection Observer API, this package is even more easier to drop into your application!
Installation
npm install use-is-in-viewport
yarn or any other package manager will also work.
You can also directly import the module from unpkg either in your html or in
your javascript.
Please note that this hook declares react and as peer dependency. Therefore, you must have
react installed to use this package.
Note: This hook relies on Intersection Observer API and hence if you want to use it in a browser that doesn't support it, the onus of shipping the polyfill is on the developer.
Please open an issue if these defaults cause a problem in your application.
API
useIsInViewport([options]) => [boolean | null, TargetCbRef, ViewportCbRef]
The nomenclature (target, viewport, threshold, etc) are borrowed from that of the Intersection Observer API
Return value
It returns an array that contains the following in order:
- a flag that is one of
null,true,falsebased on the visibility of target element in provided viewportnull-> first call to the hook when nothing is initializedtrue-> target element is visible in the given viewportfalse-> target element is visible in the given viewport
- A callback ref to pass to the element you want to know the visibility of.
- A callback ref to pass to the element you want to use as the viewport.
Options
The hook accepts an optional options object. When not provided, "sane" defaults are used. They are
described in the options section below.
options.threshold
The threshold describes what percent of the target element should intersect with the given viewport for it to be considered as visible in the viewport.
It can be a number or an array of numbers. The number is interpreted as a percent of the target element's dimensions.
Passing an array of numbers is likely to be useless for most use cases. It only exists as an artefact of the library this hook is built on and hence will most likely will be deprecated and removed based on feedback from the community.
Default: 0% -> as soon as even 1px of your target element is visible in viewport it'll be
reported as visible in viewport.
Example:
1// this would report an element as visible in its parent document viewport when 2// at least 50% of the target intersects with the viewport 3const [isInViewport, targetRef] = useIsInViewport({ threshold: 50 }) 4... 5<div ref={wrappedTargetRef}>{ isInViewport ? 'Visible' : 'Nope' }</div>
options.target
The target accepts a ref for the element you want
track the visibility of in a viewport. This is useful when you have a ref that is created outside
of this hook (for e.g., passed in via ref prop from another component, a forwarded ref, etc).
This ref is wrapped and a new ref is returned at index 1 in the returned array. The returned ref is
what you must pass to the ref property of the element you want to track the visibility of.
Default: undefined
Example:
1const targetRef = useCallback(node => console.log(node)) // can come from anywhere
2// or
3const targetRef = useRef(null) // can come from anywhere
4
5const [isInViewport, wrappedTargetRef] = useIsInViewport({ target: targetRef })
6...
7<div ref={wrappedTargetRef}>{ isInViewport ? 'Visible' : 'Nope' }</div>options.viewport
The viewport accepts a ref for the element you
want to use as the viewport. This must be a parent of the element you want to track the visibility
of. This options is useful when you have a ref that is created outside of this hook (for e.g.,
passed in via ref prop from another component, a forwarded ref, etc).
This ref is wrapped and a new ref is returned at index 2 in the returned array. The returned ref is
what you must pass to the ref property of the element you want to use as the viewport.
Also, if you want plan to use the same viewport for multiple child elements, then the viewport ref must be chained as shown in the example below. This might feel a bit weird at first but this chaining is necessary so that we can -
- Preserve whatever behaviour the incoming viewport ref has (it could be a fn or a object ref)
- Have only one viewport ref that can then be passed to the element you want to use as viewport
Default: undefined
Example:
1const MyElement = React.forwardRef(function MyElement(props, parentRef) {
2 const [isFirstDivInViewport, firstDiv, wrappedViewportRef] = useIsInViewport({
3 viewport: parentRef
4 })
5 const [isSecondDivInViewport, secondDiv, finalViewportRef] = useIsInViewport({
6 viewport: wrappedViewportRef, // viewport ref is chained
7 threshold: 20
8 })
9
10 return (
11 <section ref={finalViewportRef}>
12 <div ref={firstDiv}>{isFirstDivInViewport ? 'Visible' : 'Nope'}</div>
13 <div ref={secondDiv}>{isSecondDivInViewport ? 'Visible' : 'Nope'}</div>
14 </section>
15 )
16})
17
18
19function App() {
20 const ref = // however you want to create a ref (useRef, raw fn, useCallback, useMemo, React.createRef, etc)
21
22 return <MyElement ref={ref} />
23}
24options.{modTop, modRight, modBottom, modLeft}
These values map directly to
rootMargin
in Intersection Observer API. The can have values similar to the CSS
margin property.
The values in rootMargin define offsets added to each side of the intersection root's bounding box to create the final intersection root bounds.
Defaults:
modTop:'0px'modRight:'0px'modBottom:'0px'modLeft:'0px'
Example:
1... 2const [isInViewport, targetRef] = useIsInViewport({ 3 modTop: '10px', 4 modRight: '1em', 5 modBottom: '2.5rem', 6 modLeft: '10%' 7}) 8...
Example usage
A CRA based example app (which is also used in the test suite) can be found under examples/cra. Inline examples showcasing some of the use-cases are below.
Example 1: Element with its parent document as viewport
As soon as at least 1px of the target div is visible in the parent document viewport,
isInViewport evaluates to true.
1import React from 'react' 2import useIsInViewport from 'use-is-in-viewport' 3 4export default function MyElement() { 5 const [isInViewport, targetRef] = useIsInViewport() 6 7 return ( 8 <div ref={targetRef}> 9 <p>{isInViewport ? 'In viewport' : 'Out of viewport'}</p> 10 </div> 11 ) 12}
Example 2: Element with a custom viewport
As soon as at least 1px of the target div is visible in its parent div (chosen as the parent by
passing viewportRef to it), isInViewport evaluates to true.
1import React from 'react' 2import useIsInViewport from 'use-is-in-viewport' 3 4export default function MyElement() { 5 const [isInViewport, targetRef, viewportRef] = useIsInViewport() 6 7 return ( 8 <div ref={viewportRef}> 9 <div ref={targetRef}> 10 <p>{isInViewport ? 'In viewport' : 'Out of viewport'}</p> 11 </div> 12 </div> 13 ) 14}
Example 3: Using a forwarded ref for the target element
In some cases, the parent element might want to control the ref of some element inside your
component. It is obviously up to your component to decide what element to assign the incoming ref.
In this example, we assign the incoming ref to the target element that we are watching for in the
document viewport. To do so, we thread it through useIsInViewport hook by using the target
option and assining the incoming ref to it. The hook takes care of updating the incoming ref
such that it is completely transparent to the parent element that passed the ref in.
1import React from 'react' 2import useIsInViewport from 'use-is-in-viewport' 3 4export const RefForwardingElement = React.forwardRef(function RefForwardingElement( 5 props, 6 incomingTargetRef 7) { 8 const [isInViewport, targetRef] = useIsInViewport({ 9 target: incomingTargetRef // thread the incoming target ref through the hook 10 }) 11 12 return ( 13 <div ref={targetRef}> 14 <p>{isInViewport ? 'In viewport' : 'Out of viewport'}</p> 15 </div> 16 ) 17})
Example 4: Using a forwarded ref for the viewport element
Same as the previous example, but here we thread the incoming ref into the viewport element
instead of the target element.
1import React from 'react' 2import useIsInViewport from 'use-is-in-viewport' 3 4export const RefForwardingElement = React.forwardRef(function RefForwardingElement( 5 props, 6 incomingViewportRef 7) { 8 const [isInViewport, targetRef, viewportRef] = useIsInViewport({ 9 viewport: incomingViewportRef // thread the incoming viewport ref through the hook 10 }) 11 12 return ( 13 <div ref={viewportRef}> 14 <div ref={targetRef}> 15 <p>{isInViewport ? 'In viewport' : 'Out of viewport'}</p> 16 </div> 17 </div> 18 ) 19})
Example 5: Tracking visibility in a custom viewport of multiple elements
In this example, we have a custom viewport element and we want to track whether its child divs are
in viewport or not. We have also chosen to use different thresholds for the two child target
divs.
As you might notice, we thread the viewport ref from the first call to useIsInViewport into the
second call to useIsInViewport. This is because an element can only be assigned one ref. And
here that element is the viewport element. Therefore, we use the transparent ref update capability
of useIsInViewport (as shown in the previous examples) to wrap the viewport ref from the first
call of the hook with a new one that is then passed to the viewport div.
1import React from 'react' 2import useIsInViewport from 'use-is-in-viewport' 3 4export default function MyElement() { 5 const [isDivOneInViewport, divOneTargetRef, viewportRefToChain] = useIsInViewport({ 6 threshold: 50 7 }) 8 const [isDivTwoInViewport, divTwoTargetRef, viewportRef] = useIsInViewport({ 9 viewport: viewportRefToChain, 10 threshold: 75 11 }) 12 13 return ( 14 <div ref={viewportRef}> 15 <div ref={divOneTargetRef}> 16 <p>{isDivOneInViewport ? 'Div one In viewport' : 'Div one out of viewport'}</p> 17 </div> 18 <div ref={divTwoTargetRef}> 19 <p>{isDivTwoInViewport ? 'Div two in viewport' : 'Div two out of viewport'}</p> 20 </div> 21 </div> 22 ) 23}
Example 6: Composing with useState to create a custom hook that clamps to true once the target element is in viewport
1import { useState } from 'react'
2import useIsInViewport from 'use-is-in-viewport'
3
4export function useClampedIsInViewport(options) {
5 const [isInViewport, ...etc] = useIsInViewport(options)
6 const [wasInViewportAtleastOnce, setWasInViewportAtleastOnce] = useState(isInViewport)
7
8 setWasInViewportAtleastOnce(prev => {
9 // this will clamp it to the first true
10 // received from useIsInViewport
11 if (!prev) {
12 return isInViewport
13 }
14 return prev
15 })
16
17 return [wasInViewportAtleastOnce, ...etc]
18}
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
Found 3/18 approved changesets -- score normalized to 1
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 16 are checked with a SAST tool
Reason
48 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-fwr7-v2mv-hh25
- Warn: Project is vulnerable to: GHSA-4w2v-q235-vp99
- Warn: Project is vulnerable to: GHSA-cph5-m8f7-6c5x
- Warn: Project is vulnerable to: GHSA-wf5p-g6vw-rhxx
- Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6
- Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx
- Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-257v-vj4p-3w2h
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c
- Warn: Project is vulnerable to: GHSA-74fj-2j2h-c42q
- Warn: Project is vulnerable to: GHSA-pw2r-vq6v-hr8c
- Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
- Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
- Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97
- Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j
- Warn: Project is vulnerable to: GHSA-7r28-3m3f-r2pr
- Warn: Project is vulnerable to: GHSA-r8j5-h5cx-65gg
- Warn: Project is vulnerable to: GHSA-2pr6-76vf-7546
- Warn: Project is vulnerable to: GHSA-8j8c-7jfh-h6hx
- Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
- Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
- Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
- Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
- Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
- Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9
- Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m
- Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
- Warn: Project is vulnerable to: GHSA-8hfj-j24r-96c4
- Warn: Project is vulnerable to: GHSA-wc69-rhjr-hc9g
- Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
- Warn: Project is vulnerable to: GHSA-566m-qj78-rww5
- Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
- Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
- Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-h9rv-jmmf-4pgx
- Warn: Project is vulnerable to: GHSA-hxcc-f52p-wc94
- Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v
- Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp
Score
2.1
/10
Last Scanned on 2025-03-03
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More