rename useOnInViewChanged to useOnInView - refactor useOnInView initialInView option to trigger

Author: jantimon

README.md

@@ -236,13 +236,13 @@ You can read more about this on these links:
 - [w3c/IntersectionObserver: Cannot track intersection with an iframe's viewport](https://github.com/w3c/IntersectionObserver/issues/372)
 - [w3c/Support iframe viewport tracking](https://github.com/w3c/IntersectionObserver/pull/465)
 
-### `useOnInViewChanged` hook
+### `useOnInView` hook
 
 ```js
-const inViewRef = useOnInViewChanged(
+const inViewRef = useOnInView(
   (enterEntry) => {
     // Do something with the element that came into view
-    console.log('Element is in view', enterEntry?.element);
+    console.log('Element is in view', enterEntry?.target);
 
     // Optionally return a cleanup function
     return (exitEntry) => {
@@ -253,23 +253,25 @@ const inViewRef = useOnInViewChanged(
 );
 ```
 
-The `useOnInViewChanged` hook provides a more direct alternative to `useInView`. It takes a callback function and returns a ref that you can assign to the DOM element you want to monitor. When the element enters the viewport, your callback will be triggered.
+The `useOnInView` hook provides a more direct alternative to `useInView`. It takes a callback function and returns a ref that you can assign to the DOM element you want to monitor. When the element enters the viewport, your callback will be triggered.
 
 Key differences from `useInView`:
 - **No re-renders** - This hook doesn't update any state, making it ideal for performance-critical scenarios
 - **Direct element access** - Your callback receives the actual DOM element and the IntersectionObserverEntry
-- **Optional cleanup** - Return a function from your callback to run when the element leaves the viewport or is unmounted
-- **Same options** - Accepts all the same [options](#options) as `useInView` except `onChange`
+- **Optional cleanup** - Return a function from your callback to run when the element leaves the viewport
+- **Similar options** - Accepts all the same [options](#options) as `useInView` except `onChange` and `initialInView`
+
+The `trigger` option allows to listen for the element entering the viewport or leaving the viewport. The default is `enter`.
 
 ```jsx
 import React from "react";
-import { useOnInViewChanged } from "react-intersection-observer";
+import { useOnInView } from "react-intersection-observer";
 
 const Component = () => {
   // Track when element appears without causing re-renders
-  const trackingRef = useOnInViewChanged((element, entry) => {
+  const trackingRef = useOnInView((entry) => {
     // Element is in view - perhaps log an impression
-    console.log("Element appeared in view");
+    console.log("Element appeared in view", entry.target);
 
     // Return optional cleanup function
     return () => {
@@ -278,6 +280,8 @@ const Component = () => {
   }, {
     /* Optional options */
     threshold: 0.5,
+    trigger: "enter",
+    triggerOnce: true,
   });
 
   return (
@@ -286,8 +290,6 @@ const Component = () => {
     </div>
   );
 };
-
-export default Component;
 ```
 
 ## Testing

src/__tests__/useOnInViewChanged.test.tsx src/__tests__/useOnInView.test.tsx

@@ -1,24 +1,23 @@
 import { render } from "@testing-library/react";
 import React, { useCallback } from "react";
-import type { IntersectionListenerOptions } from "../index";
+import type { IntersectionEffectOptions } from "..";
 import { intersectionMockInstance, mockAllIsIntersecting } from "../test-utils";
-import { useOnInViewChanged } from "../useOnInViewChanged";
+import { useOnInView } from "../useOnInView";
 
 const OnInViewChangedComponent = ({
   options,
   unmount,
 }: {
-  options?: IntersectionListenerOptions;
+  options?: IntersectionEffectOptions;
   unmount?: boolean;
 }) => {
   const [inView, setInView] = React.useState(false);
   const [callCount, setCallCount] = React.useState(0);
   const [cleanupCount, setCleanupCount] = React.useState(0);
 
-  const inViewRef = useOnInViewChanged((entry) => {
-    setInView(entry ? entry.isIntersecting : false);
+  const inViewRef = useOnInView((entry) => {
+    setInView(entry.isIntersecting);
     setCallCount((prev) => prev + 1);
-
     // Return cleanup function
     return (cleanupEntry) => {
       setCleanupCount((prev) => prev + 1);
@@ -44,7 +43,7 @@ const OnInViewChangedComponent = ({
 const LazyOnInViewChangedComponent = ({
   options,
 }: {
-  options?: IntersectionListenerOptions;
+  options?: IntersectionEffectOptions;
 }) => {
   const [isLoading, setIsLoading] = React.useState(true);
   const [inView, setInView] = React.useState(false);
@@ -53,7 +52,7 @@ const LazyOnInViewChangedComponent = ({
     setIsLoading(false);
   }, []);
 
-  const inViewRef = useOnInViewChanged((entry) => {
+  const inViewRef = useOnInView((entry) => {
     setInView(entry ? entry.isIntersecting : false);
     return () => setInView(false);
   }, options);
@@ -71,11 +70,11 @@ const OnInViewChangedComponentWithoutClenaup = ({
   options,
   unmount,
 }: {
-  options?: IntersectionListenerOptions;
+  options?: IntersectionEffectOptions;
   unmount?: boolean;
 }) => {
   const [callCount, setCallCount] = React.useState(0);
-  const inViewRef = useOnInViewChanged(() => {
+  const inViewRef = useOnInView(() => {
     setCallCount((prev) => prev + 1);
   }, options);
 
@@ -88,7 +87,7 @@ const OnInViewChangedComponentWithoutClenaup = ({
   );
 };
 
-test("should create a hook with useOnInViewChanged", () => {
+test("should create a hook with useOnInView", () => {
   const { getByTestId } = render(<OnInViewChangedComponent />);
   const wrapper = getByTestId("wrapper");
   const instance = intersectionMockInstance(wrapper);
@@ -106,7 +105,7 @@ test("should create a hook with array threshold", () => {
   expect(instance.observe).toHaveBeenCalledWith(wrapper);
 });
 
-test("should create a lazy hook with useOnInViewChanged", () => {
+test("should create a lazy hook with useOnInView", () => {
   const { getByTestId } = render(<LazyOnInViewChangedComponent />);
   const wrapper = getByTestId("wrapper");
   const instance = intersectionMockInstance(wrapper);
@@ -149,16 +148,38 @@ test("should respect threshold values", () => {
   expect(wrapper.getAttribute("data-inview")).toBe("true");
 });
 
-test("should call callback with initialInView", () => {
+test("should call callback with trigger: leave", () => {
   const { getByTestId } = render(
-    <OnInViewChangedComponent options={{ initialInView: true }} />,
+    <OnInViewChangedComponent options={{ trigger: "leave" }} />,
   );
   const wrapper = getByTestId("wrapper");
 
-  // initialInView should have triggered the callback once
+  mockAllIsIntersecting(false);
+  // Should call callback
   expect(wrapper.getAttribute("data-call-count")).toBe("1");
 
+  mockAllIsIntersecting(true);
+  // Should call cleanup
+  expect(wrapper.getAttribute("data-cleanup-count")).toBe("1");
+});
+
+test("should call callback with trigger: leave and triggerOnce is true", () => {
+  const { getByTestId } = render(
+    <OnInViewChangedComponent
+      options={{ trigger: "leave", triggerOnce: true }}
+    />,
+  );
+  const wrapper = getByTestId("wrapper");
+
+  mockAllIsIntersecting(true);
+  // initialInView should have triggered the callback once
+  expect(wrapper.getAttribute("data-call-count")).toBe("0");
+
   mockAllIsIntersecting(false);
+  // Should call callback
+  expect(wrapper.getAttribute("data-call-count")).toBe("1");
+
+  mockAllIsIntersecting(true);
   // Should call cleanup
   expect(wrapper.getAttribute("data-cleanup-count")).toBe("1");
 });
@@ -229,10 +250,10 @@ test("should handle ref changes", () => {
 // Test for merging refs
 const MergeRefsComponent = ({
   options,
-}: { options?: IntersectionListenerOptions }) => {
+}: { options?: IntersectionEffectOptions }) => {
   const [inView, setInView] = React.useState(false);
 
-  const inViewRef = useOnInViewChanged((entry) => {
+  const inViewRef = useOnInView((entry) => {
     setInView(entry ? entry.isIntersecting : false);
     return () => setInView(false);
   }, options);
@@ -258,22 +279,22 @@ test("should handle merged refs", () => {
 // Test multiple callbacks on the same element
 const MultipleCallbacksComponent = ({
   options,
-}: { options?: IntersectionListenerOptions }) => {
+}: { options?: IntersectionEffectOptions }) => {
   const [inView1, setInView1] = React.useState(false);
   const [inView2, setInView2] = React.useState(false);
   const [inView3, setInView3] = React.useState(false);
 
-  const ref1 = useOnInViewChanged((entry) => {
+  const ref1 = useOnInView((entry) => {
     setInView1(entry ? entry.isIntersecting : false);
     return () => setInView1(false);
   }, options);
 
-  const ref2 = useOnInViewChanged((entry) => {
+  const ref2 = useOnInView((entry) => {
     setInView2(entry ? entry.isIntersecting : false);
     return () => setInView2(false);
   }, options);
 
-  const ref3 = useOnInViewChanged((entry) => {
+  const ref3 = useOnInView((entry) => {
     setInView3(entry ? entry.isIntersecting : false);
     return () => setInView3(false);
   });
@@ -316,7 +337,7 @@ test("should pass the element to the callback", () => {
   let capturedElement: Element | undefined;
 
   const ElementTestComponent = () => {
-    const inViewRef = useOnInViewChanged((entry) => {
+    const inViewRef = useOnInView((entry) => {
       capturedElement = entry?.target;
       return undefined;
     });

src/index.tsx

@@ -3,7 +3,7 @@
 import type * as React from "react";
 export { InView } from "./InView";
 export { useInView } from "./useInView";
-export { useOnInViewChanged } from "./useOnInViewChanged";
+export { useOnInView } from "./useOnInView";
 export { observe } from "./observe";
 
 type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
@@ -20,7 +20,7 @@ interface RenderProps {
   ref: React.RefObject<any> | ((node?: Element | null) => void);
 }
 
-export interface IntersectionListenerOptions extends IntersectionObserverInit {
+export interface IntersectionBaseOptions extends IntersectionObserverInit {
   /** 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.*/
   root?: Element | Document | null;
   /** Margin around the root. Can have values similar to the CSS margin property, e.g. `10px 20px 30px 40px` (top, right, bottom, left). */
@@ -31,17 +31,22 @@ export interface IntersectionListenerOptions extends IntersectionObserverInit {
   triggerOnce?: boolean;
   /** Skip assigning the observer to the `ref` */
   skip?: boolean;
-  /** 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. */
-  initialInView?: boolean;
   /** IntersectionObserver v2 - Track the actual visibility of the element */
   trackVisibility?: boolean;
   /** IntersectionObserver v2 - Set a minimum delay between notifications */
   delay?: number;
 }
 
-export interface IntersectionOptions extends IntersectionListenerOptions {
+export interface IntersectionOptions extends IntersectionBaseOptions {
   /** Call this function whenever the in view state changes */
   onChange?: (inView: boolean, entry: IntersectionObserverEntry) => void;
+  /** 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. */
+  initialInView?: boolean;
+}
+
+export interface IntersectionEffectOptions extends IntersectionBaseOptions {
+  /** When to trigger the inView callback - default: "enter" */
+  trigger?: "enter" | "leave";
 }
 
 export interface IntersectionObserverProps extends IntersectionOptions {
@@ -86,14 +91,14 @@ export type InViewHookResponse = [
 };
 
 /**
- * The callback called by the useOnInViewChanged hook once the element is in view
+ * The callback called by the useOnInView hook once the element is in view
  *
  * Allows to return a cleanup function that will be called when the element goes out of view or when the observer is destroyed
  */
-export type InViewEnterHookListener<TElement extends Element> = (
-  /** Entry is always defined except when `initialInView` is true for the first call */
-  entry: (IntersectionObserverEntry & { target: TElement }) | undefined,
+export type IntersectionChangeEffect<TElement extends Element> = (
+  entry: IntersectionObserverEntry & { target: TElement },
 ) => // biome-ignore lint/suspicious/noConfusingVoidType: Allow no return statement
   | void
   | undefined
+  /** Entry is defined except when the element is unmounting */
   | ((entry?: IntersectionObserverEntry | undefined) => void);

src/useInView.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 import type { InViewHookResponse, IntersectionOptions } from "./index";
-import { useOnInViewChanged } from "./useOnInViewChanged";
+import { useOnInView } from "./useOnInView";
 
 type State = {
   inView: boolean;
@@ -38,10 +38,10 @@ export function useInView(
 ): InViewHookResponse {
   const {
     threshold,
-    delay,
-    trackVisibility,
-    rootMargin,
     root,
+    rootMargin,
+    trackVisibility,
+    delay,
     triggerOnce,
     skip,
     initialInView,
@@ -58,17 +58,18 @@ export function useInView(
   const latestOptions = React.useRef(options);
   latestOptions.current = options;
 
-  // Create the ref tracking function using useOnInViewChanged
-  const refCallback = useOnInViewChanged(
+  // Create the ref tracking function using useOnInView
+  const refCallback = useOnInView(
     // Combined callback - updates state, calls onChange, and returns cleanup if needed
     (entry) => {
-      setState({ inView: true, entry });
+      const inView = !initialInView;
+      setState({ inView, entry });
 
       const { onChange } = latestOptions.current;
       // Call the external onChange if provided
       // entry is undefined only if this is triggered by initialInView
-      if (onChange && entry) {
-        onChange(true, entry);
+      if (onChange) {
+        onChange(inView, entry);
       }
 
       return triggerOnce
@@ -81,28 +82,28 @@ export function useInView(
             // Call the external onChange if provided
             // entry is undefined if the element is getting unmounted
             if (onChange && entry) {
-              onChange(false, entry);
+              onChange(!inView, entry);
             }
             // should not reset current state if changing skip
             if (!skip) {
               setState({
-                inView: false,
+                inView: !inView,
                 entry: undefined,
               });
             }
           };
     },
     {
+      threshold,
       root,
       rootMargin,
-      threshold,
       // @ts-ignore
       trackVisibility,
       // @ts-ignore
       delay,
-      initialInView,
       triggerOnce,
       skip,
+      trigger: initialInView ? "leave" : undefined,
     },
   );