` will be
82 | passed to the HTML element, allowing you set the `className`, `style`, etc.
83 |
84 | ```jsx
85 | import { InView } from 'react-intersection-observer';
86 |
87 | const Component = () => (
88 | console.log('Inview:', inView)}>
89 | Plain children are always rendered. Use onChange to monitor state.
90 |
91 | );
92 |
93 | export default Component;
94 | ```
95 |
96 | [](https://codesandbox.io/s/inview-plain-children-vv51y?fontsize=14&hidenavigation=1&theme=dark)
97 |
98 | > ⚠️ When rendering a plain child, make sure you keep your HTML output semantic.
99 | > Change the `as` to match the context, and add a `className` to style the
100 | > ``. The component does not support Ref Forwarding, so if you need a
101 | > `ref` to the HTML element, use the Render Props version instead.
102 |
103 | ## API
104 |
105 | ### Options
106 |
107 | Provide these as props on the **``** component or as the options
108 | argument for the hooks.
109 |
110 | | Name | Type | Default | Required | Description |
111 | | ---------------------- | ------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112 | | **root** | Element | document | false | The IntersectionObserver interface's read-only root property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the root is null, then the bounds of the actual document viewport are used. |
113 | | **rootMargin** | string | '0px' | false | Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). |
114 | | **threshold** | number \| number[] | 0 | false | Number between 0 and 1 indicating the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points. |
115 | | **trackVisibility** 🧪 | boolean | false | false | A boolean indicating whether this IntersectionObserver will track changes in a target’s visibility. |
116 | | **delay** 🧪 | number | undefined | false | A number indicating the minimum delay in milliseconds between notifications from this observer for a given target. This must be set to at least `100` if `trackVisibility` is `true`. |
117 | | **skip** | boolean | false | false | Skip creating the IntersectionObserver. You can use this to enable and disable the observer as needed. If `skip` is set while `inView`, the current state will still be kept. |
118 | | **triggerOnce** | boolean | false | false | Only trigger the observer once. |
119 | | **initialInView** | boolean | false | false | Set the initial value of the `inView` boolean. This can be used if you expect the element to be in the viewport to start with, and you want to trigger something when it leaves. |
120 | | **fallbackInView** | `boolean` | undefined | false | If the `IntersectionObserver` API isn't available in the client, the default behavior is to throw an Error. You can set a specific fallback behavior, and the `inView` value will be set to this instead of failing. To set a global default, you can set it with the `defaultFallbackInView()` |
121 |
122 | ### InView Props
123 |
124 | The **``** component also accepts the following props:
125 |
126 | | Name | Type | Default | Required | Description |
127 | | ------------ | -------------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128 | | **as** | `string` | 'div' | false | Render the wrapping element as this element. Defaults to `div`. |
129 | | **children** | `({ref, inView, entry}) => React.ReactNode`, `ReactNode` | | true | Children expects a function that receives an object containing the `inView` boolean and a `ref` that should be assigned to the element root. Alternatively pass a plain child, to have the `` deal with the wrapping element. You will also get the `IntersectionObserverEntry` as `entry, giving you more details. |
130 | | **onChange** | `(inView, entry) => void` | | false | Call this function whenever the in view state changes. It will receive the `inView` boolean, alongside the current `IntersectionObserverEntry`. |
131 |
--------------------------------------------------------------------------------
/src/__tests__/useInView.test.tsx:
--------------------------------------------------------------------------------
1 | import { render, screen } from "@testing-library/react";
2 | import React, { useCallback } from "react";
3 | import { defaultFallbackInView, type IntersectionOptions } from "../index";
4 | import {
5 | destroyIntersectionMocking,
6 | intersectionMockInstance,
7 | mockAllIsIntersecting,
8 | mockIsIntersecting,
9 | } from "../test-utils";
10 | import { useInView } from "../useInView";
11 |
12 | const HookComponent = ({
13 | options,
14 | unmount,
15 | }: {
16 | options?: IntersectionOptions;
17 | unmount?: boolean;
18 | }) => {
19 | const [ref, inView] = useInView(options);
20 | return (
21 |
22 | {inView.toString()}
23 |
24 | );
25 | };
26 |
27 | const LazyHookComponent = ({ options }: { options?: IntersectionOptions }) => {
28 | const [isLoading, setIsLoading] = React.useState(true);
29 |
30 | React.useEffect(() => {
31 | setIsLoading(false);
32 | }, []);
33 | const [ref, inView] = useInView(options);
34 | if (isLoading) return Loading
;
35 | return (
36 |
37 | {inView.toString()}
38 |
39 | );
40 | };
41 |
42 | test("should create a hook", () => {
43 | const { getByTestId } = render();
44 | const wrapper = getByTestId("wrapper");
45 | const instance = intersectionMockInstance(wrapper);
46 |
47 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
48 | });
49 |
50 | test("should create a hook with array threshold", () => {
51 | const { getByTestId } = render(
52 | ,
53 | );
54 | const wrapper = getByTestId("wrapper");
55 | const instance = intersectionMockInstance(wrapper);
56 |
57 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
58 | });
59 |
60 | test("should create a lazy hook", () => {
61 | const { getByTestId } = render();
62 | const wrapper = getByTestId("wrapper");
63 | const instance = intersectionMockInstance(wrapper);
64 |
65 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
66 | });
67 |
68 | test("should create a hook inView", () => {
69 | const { getByText } = render();
70 | mockAllIsIntersecting(true);
71 |
72 | getByText("true");
73 | });
74 |
75 | test("should mock thresholds", () => {
76 | render();
77 | mockAllIsIntersecting(0.2);
78 | screen.getByText("false");
79 | mockAllIsIntersecting(0.5);
80 | screen.getByText("true");
81 | mockAllIsIntersecting(1);
82 | screen.getByText("true");
83 | });
84 |
85 | test("should create a hook with initialInView", () => {
86 | const { getByText } = render(
87 | ,
88 | );
89 | getByText("true");
90 | mockAllIsIntersecting(false);
91 | getByText("false");
92 | });
93 |
94 | test("should trigger a hook leaving view", () => {
95 | const { getByText } = render();
96 | mockAllIsIntersecting(true);
97 | mockAllIsIntersecting(false);
98 | getByText("false");
99 | });
100 |
101 | test("should respect trigger once", () => {
102 | const { getByText } = render(
103 | ,
104 | );
105 | mockAllIsIntersecting(true);
106 | mockAllIsIntersecting(false);
107 |
108 | getByText("true");
109 | });
110 |
111 | test("should trigger onChange", () => {
112 | const onChange = vi.fn();
113 | render();
114 |
115 | mockAllIsIntersecting(false);
116 | expect(onChange).not.toHaveBeenCalled();
117 |
118 | mockAllIsIntersecting(true);
119 | expect(onChange).toHaveBeenLastCalledWith(
120 | true,
121 | expect.objectContaining({ intersectionRatio: 1, isIntersecting: true }),
122 | );
123 |
124 | mockAllIsIntersecting(false);
125 | expect(onChange).toHaveBeenLastCalledWith(
126 | false,
127 | expect.objectContaining({ intersectionRatio: 0, isIntersecting: false }),
128 | );
129 | });
130 |
131 | test("should respect skip", () => {
132 | const { getByText, rerender } = render(
133 | ,
134 | );
135 | mockAllIsIntersecting(false);
136 | getByText("false");
137 |
138 | rerender();
139 | mockAllIsIntersecting(true);
140 | getByText("true");
141 | });
142 |
143 | test("should not reset current state if changing skip", () => {
144 | const { getByText, rerender } = render(
145 | ,
146 | );
147 | mockAllIsIntersecting(true);
148 | rerender();
149 | getByText("true");
150 | });
151 |
152 | test("should unmount the hook", () => {
153 | const { unmount, getByTestId } = render();
154 | const wrapper = getByTestId("wrapper");
155 | const instance = intersectionMockInstance(wrapper);
156 | unmount();
157 | expect(instance.unobserve).toHaveBeenCalledWith(wrapper);
158 | });
159 |
160 | test("inView should be false when component is unmounted", () => {
161 | const { rerender, getByText } = render();
162 | mockAllIsIntersecting(true);
163 |
164 | getByText("true");
165 | rerender();
166 | getByText("false");
167 | });
168 |
169 | test("should handle trackVisibility", () => {
170 | render();
171 | mockAllIsIntersecting(true);
172 | });
173 |
174 | test("should handle trackVisibility when unsupported", () => {
175 | render();
176 | });
177 |
178 | const SwitchHookComponent = ({
179 | options,
180 | toggle,
181 | unmount,
182 | }: {
183 | options?: IntersectionOptions;
184 | toggle?: boolean;
185 | unmount?: boolean;
186 | }) => {
187 | const [ref, inView] = useInView(options);
188 | return (
189 | <>
190 |
195 |
200 |
201 | );
202 | };
203 |
204 | /**
205 | * This is a test for the case where people move the ref around (please don't)
206 | */
207 | test("should handle ref removed", () => {
208 | const { rerender, getByTestId } = render();
209 | mockAllIsIntersecting(true);
210 |
211 | const item1 = getByTestId("item-1");
212 | const item2 = getByTestId("item-2");
213 |
214 | // Item1 should be inView
215 | expect(item1.getAttribute("data-inview")).toBe("true");
216 | expect(item2.getAttribute("data-inview")).toBe("false");
217 |
218 | rerender();
219 | mockAllIsIntersecting(true);
220 |
221 | // Item2 should be inView
222 | expect(item1.getAttribute("data-inview")).toBe("false");
223 | expect(item2.getAttribute("data-inview")).toBe("true");
224 |
225 | rerender();
226 |
227 | // Nothing should be inView
228 | expect(item1.getAttribute("data-inview")).toBe("false");
229 | expect(item2.getAttribute("data-inview")).toBe("false");
230 |
231 | // Add the ref back
232 | rerender();
233 | mockAllIsIntersecting(true);
234 | expect(item1.getAttribute("data-inview")).toBe("true");
235 | expect(item2.getAttribute("data-inview")).toBe("false");
236 | });
237 |
238 | const MergeRefsComponent = ({ options }: { options?: IntersectionOptions }) => {
239 | const [inViewRef, inView] = useInView(options);
240 | const setRef = useCallback(
241 | (node: Element | null) => {
242 | inViewRef(node);
243 | },
244 | [inViewRef],
245 | );
246 |
247 | return ;
248 | };
249 |
250 | test("should handle ref merged", () => {
251 | const { rerender, getByTestId } = render();
252 | mockAllIsIntersecting(true);
253 | rerender();
254 |
255 | expect(getByTestId("inview").getAttribute("data-inview")).toBe("true");
256 | });
257 |
258 | const MultipleHookComponent = ({
259 | options,
260 | }: {
261 | options?: IntersectionOptions;
262 | }) => {
263 | const [ref1, inView1] = useInView(options);
264 | const [ref2, inView2] = useInView(options);
265 | const [ref3, inView3] = useInView();
266 |
267 | const mergedRefs = useCallback(
268 | (node: Element | null) => {
269 | ref1(node);
270 | ref2(node);
271 | ref3(node);
272 | },
273 | [ref1, ref2, ref3],
274 | );
275 |
276 | return (
277 |
278 |
279 | {inView1}
280 |
281 |
282 | {inView2}
283 |
284 |
285 | {inView3}
286 |
287 |
333 | {entry && Object.entries(entry).map(([key, value]) => `${key}: ${value}`)}
334 |
335 | );
336 | };
337 |
338 | test("should set intersection ratio as the largest threshold smaller than trigger", () => {
339 | render(
340 | ,
341 | );
342 | const wrapper = screen.getByTestId("wrapper");
343 |
344 | mockIsIntersecting(wrapper, 0.5);
345 | screen.getByText(/intersectionRatio: 0.5/);
346 | });
347 |
348 | test("should handle fallback if unsupported", () => {
349 | destroyIntersectionMocking();
350 | // @ts-expect-error
351 | window.IntersectionObserver = undefined;
352 | const { rerender } = render(
353 | ,
354 | );
355 | screen.getByText("true");
356 |
357 | rerender();
358 | screen.getByText("false");
359 |
360 | expect(() => {
361 | vi.spyOn(console, "error").mockImplementation(() => {});
362 | rerender();
363 | // @ts-expect-error
364 | console.error.mockRestore();
365 | }).toThrowErrorMatchingInlineSnapshot(
366 | `[TypeError: IntersectionObserver is not a constructor]`,
367 | );
368 | });
369 |
370 | test("should handle defaultFallbackInView if unsupported", () => {
371 | destroyIntersectionMocking();
372 | // @ts-expect-error
373 | window.IntersectionObserver = undefined;
374 | defaultFallbackInView(true);
375 | const { rerender } = render();
376 | screen.getByText("true");
377 |
378 | defaultFallbackInView(false);
379 | rerender();
380 | screen.getByText("false");
381 |
382 | defaultFallbackInView(undefined);
383 | expect(() => {
384 | vi.spyOn(console, "error").mockImplementation(() => {});
385 | rerender();
386 | // @ts-expect-error
387 | console.error.mockRestore();
388 | }).toThrowErrorMatchingInlineSnapshot(
389 | `[TypeError: IntersectionObserver is not a constructor]`,
390 | );
391 | });
392 |
393 | test("should restore the browser IntersectionObserver", () => {
394 | expect(vi.isMockFunction(window.IntersectionObserver)).toBe(true);
395 | destroyIntersectionMocking();
396 |
397 | // This should restore the original IntersectionObserver
398 | expect(window.IntersectionObserver).toBeDefined();
399 | expect(vi.isMockFunction(window.IntersectionObserver)).toBe(false);
400 | });
401 |
--------------------------------------------------------------------------------
/src/__tests__/useOnInView.test.tsx:
--------------------------------------------------------------------------------
1 | import { render } from "@testing-library/react";
2 | import { useCallback, useEffect, useState } from "react";
3 | import type { IntersectionEffectOptions } from "..";
4 | import { intersectionMockInstance, mockAllIsIntersecting } from "../test-utils";
5 | import { useOnInView } from "../useOnInView";
6 |
7 | const OnInViewChangedComponent = ({
8 | options,
9 | unmount,
10 | }: {
11 | options?: IntersectionEffectOptions;
12 | unmount?: boolean;
13 | }) => {
14 | const [inView, setInView] = useState(false);
15 | const [callCount, setCallCount] = useState(0);
16 | const [cleanupCount, setCleanupCount] = useState(0);
17 |
18 | const inViewRef = useOnInView((isInView) => {
19 | setInView(isInView);
20 | setCallCount((prev) => prev + 1);
21 | if (!isInView) {
22 | setCleanupCount((prev) => prev + 1);
23 | }
24 | }, options);
25 |
26 | return (
27 |
34 | {inView.toString()}
35 |
36 | );
37 | };
38 |
39 | const LazyOnInViewChangedComponent = ({
40 | options,
41 | }: {
42 | options?: IntersectionEffectOptions;
43 | }) => {
44 | const [isLoading, setIsLoading] = useState(true);
45 | const [inView, setInView] = useState(false);
46 |
47 | useEffect(() => {
48 | setIsLoading(false);
49 | }, []);
50 |
51 | const inViewRef = useOnInView((isInView) => {
52 | setInView(isInView);
53 | }, options);
54 |
55 | if (isLoading) return Loading
;
56 |
57 | return (
58 |
59 | {inView.toString()}
60 |
61 | );
62 | };
63 |
64 | const OnInViewChangedComponentWithoutCleanup = ({
65 | options,
66 | unmount,
67 | }: {
68 | options?: IntersectionEffectOptions;
69 | unmount?: boolean;
70 | }) => {
71 | const [callCount, setCallCount] = useState(0);
72 | const inViewRef = useOnInView(() => {
73 | setCallCount((prev) => prev + 1);
74 | }, options);
75 |
76 | return (
77 |
82 | );
83 | };
84 |
85 | const ThresholdTriggerComponent = ({
86 | options,
87 | }: {
88 | options?: IntersectionEffectOptions;
89 | }) => {
90 | const [triggerCount, setTriggerCount] = useState(0);
91 | const [cleanupCount, setCleanupCount] = useState(0);
92 | const [lastRatio, setLastRatio] = useState(null);
93 | const [triggeredThresholds, setTriggeredThresholds] = useState([]);
94 |
95 | const inViewRef = useOnInView((isInView, entry) => {
96 | setTriggerCount((prev) => prev + 1);
97 | setLastRatio(entry.intersectionRatio);
98 |
99 | if (isInView) {
100 | // Add this ratio to our list of triggered thresholds
101 | setTriggeredThresholds((prev) => [...prev, entry.intersectionRatio]);
102 | } else {
103 | setCleanupCount((prev) => prev + 1);
104 | }
105 | }, options);
106 |
107 | return (
108 |
116 | Tracking thresholds
117 |
118 | );
119 | };
120 |
121 | test("should create a hook with useOnInView", () => {
122 | const { getByTestId } = render();
123 | const wrapper = getByTestId("wrapper");
124 | const instance = intersectionMockInstance(wrapper);
125 |
126 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
127 | });
128 |
129 | test("should create a hook with array threshold", () => {
130 | const { getByTestId } = render(
131 | ,
132 | );
133 | const wrapper = getByTestId("wrapper");
134 | const instance = intersectionMockInstance(wrapper);
135 |
136 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
137 | });
138 |
139 | test("should create a lazy hook with useOnInView", () => {
140 | const { getByTestId } = render();
141 | const wrapper = getByTestId("wrapper");
142 | const instance = intersectionMockInstance(wrapper);
143 |
144 | expect(instance.observe).toHaveBeenCalledWith(wrapper);
145 | });
146 |
147 | test("should call the callback when element comes into view", () => {
148 | const { getByTestId } = render();
149 | mockAllIsIntersecting(true);
150 |
151 | const wrapper = getByTestId("wrapper");
152 | expect(wrapper.getAttribute("data-inview")).toBe("true");
153 | expect(wrapper.getAttribute("data-call-count")).toBe("1");
154 | });
155 |
156 | test("should ignore initial false intersection", () => {
157 | const { getByTestId } = render();
158 | const wrapper = getByTestId("wrapper");
159 |
160 | mockAllIsIntersecting(false);
161 | expect(wrapper.getAttribute("data-call-count")).toBe("0");
162 |
163 | mockAllIsIntersecting(true);
164 | expect(wrapper.getAttribute("data-call-count")).toBe("1");
165 | });
166 |
167 | test("should call cleanup when element leaves view", () => {
168 | const { getByTestId } = render();
169 | mockAllIsIntersecting(true);
170 | mockAllIsIntersecting(false);
171 |
172 | const wrapper = getByTestId("wrapper");
173 | expect(wrapper.getAttribute("data-inview")).toBe("false");
174 | expect(wrapper.getAttribute("data-cleanup-count")).toBe("1");
175 | });
176 |
177 | test("should respect threshold values", () => {
178 | const { getByTestId } = render(
179 | ,
180 | );
181 | const wrapper = getByTestId("wrapper");
182 |
183 | mockAllIsIntersecting(0.2);
184 | expect(wrapper.getAttribute("data-inview")).toBe("false");
185 |
186 | mockAllIsIntersecting(0.5);
187 | expect(wrapper.getAttribute("data-inview")).toBe("true");
188 |
189 | mockAllIsIntersecting(1);
190 | expect(wrapper.getAttribute("data-inview")).toBe("true");
191 | });
192 |
193 | test("should respect triggerOnce option", () => {
194 | const { getByTestId } = render(
195 | <>
196 |
197 |
198 | ,
199 | );
200 | const wrapper = getByTestId("wrapper");
201 | const wrapperTriggerOnce = getByTestId("wrapper-no-cleanup");
202 |
203 | mockAllIsIntersecting(true);
204 | expect(wrapper.getAttribute("data-call-count")).toBe("1");
205 | expect(wrapperTriggerOnce.getAttribute("data-call-count")).toBe("1");
206 | mockAllIsIntersecting(false);
207 | expect(wrapper.getAttribute("data-cleanup-count")).toBe("1");
208 | mockAllIsIntersecting(true);
209 | expect(wrapper.getAttribute("data-call-count")).toBe("3");
210 | expect(wrapperTriggerOnce.getAttribute("data-call-count")).toBe("1");
211 | });
212 |
213 | test("should respect skip option", () => {
214 | const { getByTestId, rerender } = render(
215 | ,
216 | );
217 | mockAllIsIntersecting(true);
218 |
219 | const wrapper = getByTestId("wrapper");
220 | expect(wrapper.getAttribute("data-inview")).toBe("false");
221 | expect(wrapper.getAttribute("data-call-count")).toBe("0");
222 |
223 | rerender();
224 | mockAllIsIntersecting(true);
225 |
226 | expect(wrapper.getAttribute("data-inview")).toBe("true");
227 | expect(wrapper.getAttribute("data-call-count")).toBe("1");
228 | });
229 |
230 | test("should handle unmounting properly", () => {
231 | const { unmount, getByTestId } = render();
232 | const wrapper = getByTestId("wrapper");
233 | const instance = intersectionMockInstance(wrapper);
234 |
235 | unmount();
236 | expect(instance.unobserve).toHaveBeenCalledWith(wrapper);
237 | });
238 |
239 | test("should handle ref changes", () => {
240 | const { rerender, getByTestId } = render();
241 | mockAllIsIntersecting(true);
242 | mockAllIsIntersecting(false);
243 |
244 | rerender();
245 |
246 | // Component should register the element leaving view before ref removal
247 | const wrapper = getByTestId("wrapper");
248 | expect(wrapper.getAttribute("data-cleanup-count")).toBe("1");
249 |
250 | // Add the ref back
251 | rerender();
252 | mockAllIsIntersecting(true);
253 |
254 | expect(wrapper.getAttribute("data-inview")).toBe("true");
255 | });
256 |
257 | // Test for merging refs
258 | const MergeRefsComponent = ({
259 | options,
260 | }: {
261 | options?: IntersectionEffectOptions;
262 | }) => {
263 | const [inView, setInView] = useState(false);
264 |
265 | const inViewRef = useOnInView((isInView) => {
266 | setInView(isInView);
267 | }, options);
268 |
269 | const setRef = useCallback(
270 | (node: Element | null) => inViewRef(node),
271 | [inViewRef],
272 | );
273 |
274 | return (
275 |
276 | );
277 | };
278 |
279 | test("should handle merged refs", () => {
280 | const { rerender, getByTestId } = render();
281 | mockAllIsIntersecting(true);
282 | rerender();
283 |
284 | expect(getByTestId("inview").getAttribute("data-inview")).toBe("true");
285 | });
286 |
287 | // Test multiple callbacks on the same element
288 | const MultipleCallbacksComponent = ({
289 | options,
290 | }: {
291 | options?: IntersectionEffectOptions;
292 | }) => {
293 | const [inView1, setInView1] = useState(false);
294 | const [inView2, setInView2] = useState(false);
295 | const [inView3, setInView3] = useState(false);
296 |
297 | const ref1 = useOnInView((isInView) => {
298 | setInView1(isInView);
299 | }, options);
300 |
301 | const ref2 = useOnInView((isInView) => {
302 | setInView2(isInView);
303 | }, options);
304 |
305 | const ref3 = useOnInView((isInView) => {
306 | setInView3(isInView);
307 | });
308 |
309 | const mergedRefs = useCallback(
310 | (node: Element | null) => {
311 | const cleanup = [ref1(node), ref2(node), ref3(node)];
312 | return () =>
313 | cleanup.forEach((fn) => {
314 | fn?.();
315 | });
316 | },
317 | [ref1, ref2, ref3],
318 | );
319 |
320 | return (
321 |
322 |
323 | {inView1.toString()}
324 |
325 |
326 | {inView2.toString()}
327 |
328 |
329 | {inView3.toString()}
330 |
331 |
70 |
{`Header inside viewport ${inView}.`}
71 |
72 | );
73 | };
74 | ```
75 |
76 | > **Note:** The first `false` notification from the underlying IntersectionObserver is ignored so your handlers only run after a real visibility change. Subsequent transitions still report both `true` and `false` states as the element enters and leaves the viewport.
77 |
78 | ### `useOnInView` hook
79 |
80 | ```js
81 | const inViewRef = useOnInView(
82 | (inView, entry) => {
83 | if (inView) {
84 | // Do something with the element that came into view
85 | console.log("Element is in view", entry.target);
86 | } else {
87 | console.log("Element left view", entry.target);
88 | }
89 | },
90 | options // Optional IntersectionObserver options
91 | );
92 | ```
93 |
94 | The `useOnInView` hook provides a more direct alternative to `useInView`. It
95 | takes a callback function and returns a ref that you can assign to the DOM
96 | element you want to monitor. Whenever the element enters or leaves the viewport,
97 | your callback will be triggered with the latest in-view state.
98 |
99 | Key differences from `useInView`:
100 | - **No re-renders** - This hook doesn't update any state, making it ideal for
101 | performance-critical scenarios
102 | - **Direct element access** - Your callback receives the actual
103 | IntersectionObserverEntry with the `target` element
104 | - **Boolean-first callback** - The callback receives the current `inView`
105 | boolean as the first argument, matching the `onChange` signature from
106 | `useInView`
107 | - **Similar options** - Accepts all the same [options](#options) as `useInView`
108 | except `onChange`, `initialInView`, and `fallbackInView`
109 |
110 | > **Note:** Just like `useInView`, the initial `false` notification is skipped. Your callback fires the first time the element becomes visible (and on every subsequent enter/leave transition).
111 |
112 | ```jsx
113 | import React from "react";
114 | import { useOnInView } from "react-intersection-observer";
115 |
116 | const Component = () => {
117 | // Track when element appears without causing re-renders
118 | const trackingRef = useOnInView(
119 | (inView, entry) => {
120 | if (inView) {
121 | // Element is in view - perhaps log an impression
122 | console.log("Element appeared in view", entry.target);
123 | } else {
124 | console.log("Element left view", entry.target);
125 | }
126 | },
127 | {
128 | /* Optional options */
129 | threshold: 0.5,
130 | triggerOnce: true,
131 | },
132 | );
133 |
134 | return (
135 |
136 |
This element is being tracked without re-renders
137 |
138 | );
139 | };
140 | ```
141 |
142 | ### Render props
143 |
144 | To use the `` component, you pass it a function. It will be called
145 | whenever the state changes, with the new value of `inView`. In addition to the
146 | `inView` prop, children also receive a `ref` that should be set on the
147 | containing DOM element. This is the element that the Intersection Observer will
148 | monitor.
149 |
150 | If you need it, you can also access the
151 | [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)
152 | on `entry`, giving you access to all the details about the current intersection
153 | state.
154 |
155 | ```jsx
156 | import { InView } from "react-intersection-observer";
157 |
158 | const Component = () => (
159 |
160 | {({ inView, ref, entry }) => (
161 |
162 |
{`Header inside viewport ${inView}.`}
163 |
164 | )}
165 |
166 | );
167 |
168 | export default Component;
169 | ```
170 |
171 | > **Note:** `` mirrors the hook behaviour—it suppresses the very first `false` notification so render props and `onChange` handlers only run after a genuine visibility change.
172 |
173 | ### Plain children
174 |
175 | You can pass any element to the ``, and it will handle creating the
176 | wrapping DOM element. Add a handler to the `onChange` method, and control the
177 | state in your own component. Any extra props you add to `` will be
178 | passed to the HTML element, allowing you set the `className`, `style`, etc.
179 |
180 | ```jsx
181 | import { InView } from "react-intersection-observer";
182 |
183 | const Component = () => (
184 | console.log("Inview:", inView)}>
185 | Plain children are always rendered. Use onChange to monitor state.
186 |
187 | );
188 |
189 | export default Component;
190 | ```
191 |
192 | > [!NOTE]
193 | > When rendering a plain child, make sure you keep your HTML output
194 | > semantic. Change the `as` to match the context, and add a `className` to style
195 | > the ``. The component does not support Ref Forwarding, so if you
196 | > need a `ref` to the HTML element, use the Render Props version instead.
197 |
198 | ## API
199 |
200 | ### Options
201 |
202 | Provide these as the options argument in the `useInView` hook or as props on the
203 | **``** component.
204 |
205 | | Name | Type | Default | Description |
206 | | ---------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207 | | **root** | `Element` | `document` | The Intersection Observer interface's read-only root property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the root is `null`, then the bounds of the actual document viewport are used. |
208 | | **rootMargin** | `string` | `'0px'` | Margin around the root. Can have values similar to the CSS margin property, e.g. `"10px 20px 30px 40px"` (top, right, bottom, left). Also supports percentages, to check if an element intersects with the center of the viewport for example `"-50% 0% -50% 0%"`. |
209 | | **threshold** | `number` or `number[]` | `0` | Number between `0` and `1` indicating the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points. |
210 | | **onChange** | `(inView, entry) => void` | `undefined` | Call this function whenever the in view state changes. It will receive the `inView` boolean, alongside the current `IntersectionObserverEntry`. |
211 | | **trackVisibility** 🧪 | `boolean` | `false` | A boolean indicating whether this Intersection Observer will track visibility changes on the target. |
212 | | **delay** 🧪 | `number` | `undefined` | A number indicating the minimum delay in milliseconds between notifications from this observer for a given target. This must be set to at least `100` if `trackVisibility` is `true`. |
213 | | **skip** | `boolean` | `false` | Skip creating the IntersectionObserver. You can use this to enable and disable the observer as needed. If `skip` is set while `inView`, the current state will still be kept. |
214 | | **triggerOnce** | `boolean` | `false` | Only trigger the observer once. |
215 | | **initialInView** | `boolean` | `false` | Set the initial value of the `inView` boolean. This can be used if you expect the element to be in the viewport to start with, and you want to trigger something when it leaves. |
216 | | **fallbackInView** | `boolean` | `undefined` | If the `IntersectionObserver` API isn't available in the client, the default behavior is to throw an Error. You can set a specific fallback behavior, and the `inView` value will be set to this instead of failing. To set a global default, you can set it with the `defaultFallbackInView()` |
217 |
218 | `useOnInView` accepts the same options as `useInView` except `onChange`,
219 | `initialInView`, and `fallbackInView`.
220 |
221 | ### InView Props
222 |
223 | The **``** component also accepts the following props:
224 |
225 | | Name | Type | Default | Description |
226 | | ------------ | ---------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
227 | | **as** | `IntrinsicElement` | `'div'` | Render the wrapping element as this element. Defaults to `div`. If you want to use a custom component, please use the `useInView` hook or a render prop instead to manage the reference explictly. |
228 | | **children** | `({ref, inView, entry}) => ReactNode` or `ReactNode` | `undefined` | Children expects a function that receives an object containing the `inView` boolean and a `ref` that should be assigned to the element root. Alternatively pass a plain child, to have the `` deal with the wrapping element. You will also get the `IntersectionObserverEntry` as `entry`, giving you more details. |
229 |
230 | ### Intersection Observer v2 🧪
231 |
232 | The new
233 | [v2 implementation of IntersectionObserver](https://developers.google.com/web/updates/2019/02/intersectionobserver-v2)
234 | extends the original API, so you can track if the element is covered by another
235 | element or has filters applied to it. Useful for blocking clickjacking attempts
236 | or tracking ad exposure.
237 |
238 | To use it, you'll need to add the new `trackVisibility` and `delay` options.
239 | When you get the `entry` back, you can then monitor if `isVisible` is `true`.
240 |
241 | ```jsx
242 | const TrackVisible = () => {
243 | const { ref, entry } = useInView({ trackVisibility: true, delay: 100 });
244 | return {entry?.isVisible}
;
245 | };
246 | ```
247 |
248 | This is still a very new addition, so check
249 | [caniuse](https://caniuse.com/#feat=intersectionobserver-v2) for current browser
250 | support. If `trackVisibility` has been set, and the current browser doesn't
251 | support it, a fallback has been added to always report `isVisible` as `true`.
252 |
253 | It's not added to the TypeScript `lib.d.ts` file yet, so you will also have to
254 | extend the `IntersectionObserverEntry` with the `isVisible` boolean.
255 |
256 | ## Recipes
257 |
258 | The `IntersectionObserver` itself is just a simple but powerful tool. Here's a
259 | few ideas for how you can use it.
260 |
261 | - [Lazy image load](docs/Recipes.md#lazy-image-load)
262 | - [Trigger animations](docs/Recipes.md#trigger-animations)
263 | - [Track impressions](docs/Recipes.md#track-impressions) _(Google Analytics, Tag
264 | Manager, etc.)_
265 |
266 | ## FAQ
267 |
268 | ### How can I assign multiple refs to a component?
269 |
270 | You can wrap multiple `ref` assignments in a single `useCallback`:
271 |
272 | ```jsx
273 | import React, { useRef, useCallback } from "react";
274 | import { useInView } from "react-intersection-observer";
275 |
276 | function Component(props) {
277 | const ref = useRef();
278 | const { ref: inViewRef, inView } = useInView();
279 |
280 | // Use `useCallback` so we don't recreate the function on each render
281 | const setRefs = useCallback(
282 | (node) => {
283 | // Ref's from useRef needs to have the node assigned to `current`
284 | ref.current = node;
285 | // Callback refs, like the one from `useInView`, is a function that takes the node as an argument
286 | inViewRef(node);
287 | },
288 | [inViewRef],
289 | );
290 |
291 | return Shared ref is visible: {inView}
;
292 | }
293 | ```
294 |
295 | ### `rootMargin` isn't working as expected
296 |
297 | When using `rootMargin`, the margin gets added to the current `root` - If your
298 | application is running inside a `
61 | ) : null}
62 |