svelte-intersection-observer 1.1.2 → 2.0.0

package/IntersectionObserver.svelte

@@ -1,116 +1,91 @@
 <script>
-  /**
-   * The HTML Element to observe.
-   * @type {null | HTMLElement}
-   */
-  export let element = null;
-
-  /**
-   * Set to `true` to unobserve the element
-   * after it intersects the viewport.
-   * @type {boolean}
-   */
-  export let once = false;
-
-  /**
-   * `true` if the observed element
-   * is intersecting the viewport.
-   */
-  export let intersecting = false;
+  import { untrack } from "svelte";
 
   /**
-   * Specify the containing element.
-   * Defaults to the browser viewport.
-   * @type {null | HTMLElement}
+   * @typedef {Object} Props
+   * @property {null | HTMLElement} [element] The HTML Element to observe.
+   * @property {boolean} [once] Set to `true` to unobserve the element after it intersects the viewport.
+   * @property {boolean} [intersecting] `true` if the observed element is intersecting the viewport.
+   * @property {null | HTMLElement} [root] Specify the containing element. Defaults to the browser viewport.
+   * @property {string} [rootMargin] Margin offset of the containing element.
+   * @property {number | number[]} [threshold] Percentage of element visibility to trigger an event. Value must be between 0 and 1.
+   * @property {null | IntersectionObserverEntry} [entry] Observed element metadata.
+   * @property {null | IntersectionObserver} [observer] `IntersectionObserver` instance.
+   * @property {boolean} [skip] Set to `true` to pause observing without disconnecting the observer or losing `entry`/`intersecting` state. Set back to `false` to resume.
+   * @property {(entry: IntersectionObserverEntry) => void} [onobserve] Called when the element is first observed and also whenever an intersection event occurs.
+   * @property {(entry: IntersectionObserverEntry & { isIntersecting: true }) => void} [onintersect] Called only when the observed element is intersecting the viewport.
+   * @property {import("svelte").Snippet<[{ intersecting: boolean, entry: null | IntersectionObserverEntry, observer: null | IntersectionObserver }]>} [children]
    */
-  export let root = null;
-
-  /** Margin offset of the containing element. */
-  export let rootMargin = "0px";
 
-  /**
-   * Percentage of element visibility to trigger an event.
-   * Value must be between 0 and 1.
-   */
-  export let threshold = 0;
-
-  /**
-   * Observed element metadata.
-   * @type {null | IntersectionObserverEntry}
-   */
-  export let entry = null;
-
-  /**
-   * `IntersectionObserver` instance.
-   * @type {null | IntersectionObserver}
-   */
-  export let observer = null;
-
-  import { tick, createEventDispatcher, afterUpdate, onMount } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  let prevRootMargin = rootMargin;
-
-  let prevThreshold = threshold;
-
-  /** @type {null | HTMLElement} */
-  let prevRoot = root;
+  /** @type {Props} */
+  let {
+    element = null,
+    once = false,
+    intersecting = $bindable(false),
+    root = null,
+    rootMargin = "0px",
+    threshold = 0,
+    entry = $bindable(null),
+    observer = $bindable(null),
+    skip = false,
+    onobserve,
+    onintersect,
+    children,
+  } = $props();
 
   /** @type {null | HTMLElement} */
   let prevElement = null;
 
+  let prevSkip = untrack(() => skip);
+
   const initialize = () => {
     observer = new IntersectionObserver(
       (entries) => {
-        entries.forEach((_entry) => {
+        for (const _entry of entries) {
           entry = _entry;
           intersecting = _entry.isIntersecting;
 
-          dispatch("observe", entry);
+          onobserve?.(_entry);
 
           if (_entry.isIntersecting) {
-            dispatch("intersect", entry);
+            onintersect?.(_entry);
 
             if (element && once) observer?.unobserve(element);
           }
-        });
+        }
       },
       { root, rootMargin, threshold },
     );
   };
 
-  onMount(() => {
+  $effect(() => {
+    prevElement = null;
     initialize();
 
     return () => {
-      if (observer) {
-        observer.disconnect();
-        observer = null;
-      }
+      observer?.disconnect();
+      observer = null;
     };
   });
 
-  afterUpdate(async () => {
-    await tick();
-
-    if (element !== null && element !== prevElement) {
-      observer?.observe(element);
+  $effect(() => {
+    const target = element;
+    const isSkipped = skip;
+    const activeObserver = observer;
 
-      if (prevElement !== null) observer?.unobserve(prevElement);
-      prevElement = element;
+    if (target !== null && target !== prevElement) {
+      if (!isSkipped) activeObserver?.observe(target);
+      if (prevElement !== null) activeObserver?.unobserve(prevElement);
+      prevElement = target;
     }
 
-    if (rootMargin !== prevRootMargin || threshold !== prevThreshold || root !== prevRoot) {
-      observer?.disconnect();
-      prevElement = null;
-      initialize();
+    if (isSkipped !== prevSkip && target !== null) {
+      if (isSkipped) activeObserver?.unobserve(target);
+      else activeObserver?.observe(target);
     }
 
-    prevRootMargin = rootMargin;
-    prevThreshold = threshold;
-    prevRoot = root;
+    prevSkip = isSkipped;
   });
 </script>
 
-<slot {intersecting} {entry} {observer} />
+{@render children?.({ intersecting, entry, observer })}

package/IntersectionObserver.svelte.d.ts

@@ -1,79 +1,95 @@
-import type { SvelteComponentTyped } from "svelte";
+import type { Component, Snippet } from "svelte";
 
-export default class extends SvelteComponentTyped<
-  {
-    /**
-     * The HTML Element to observe.
-     * @default null
-     */
-    element?: null | HTMLElement;
+export interface IntersectionObserverProps {
+  /**
+   * The HTML Element to observe.
+   * @default null
+   */
+  element?: null | HTMLElement;
 
-    /**
-     * Set to `true` to unobserve the element
-     * after it intersects the viewport.
-     * @default false
-     */
-    once?: boolean;
+  /**
+   * Set to `true` to unobserve the element
+   * after it intersects the viewport.
+   * @default false
+   */
+  once?: boolean;
 
-    /**
-     * `true` if the observed element
-     * is intersecting the viewport.
-     * @default false
-     */
-    intersecting?: boolean;
+  /**
+   * `true` if the observed element
+   * is intersecting the viewport.
+   * @default false
+   */
+  intersecting?: boolean;
 
-    /**
-     * Specify the containing element.
-     * Defaults to the browser viewport.
-     * @default null
-     */
-    root?: null | HTMLElement;
+  /**
+   * Specify the containing element.
+   * Defaults to the browser viewport.
+   * @default null
+   */
+  root?: null | HTMLElement;
 
-    /**
-     * Margin offset of the containing element.
-     * @default "0px"
-     */
-    rootMargin?: string;
+  /**
+   * Margin offset of the containing element.
+   * @default "0px"
+   */
+  rootMargin?: string;
 
-    /**
-     * Percentage of element visibility to trigger an event.
-     * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
-     * @default 0
-     */
-    threshold?: number | number[];
+  /**
+   * Percentage of element visibility to trigger an event.
+   * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
+   * @default 0
+   */
+  threshold?: number | number[];
 
-    /**
-     * Observed element metadata.
-     * @default null
-     */
-    entry?: null | IntersectionObserverEntry;
+  /**
+   * Observed element metadata.
+   * @default null
+   */
+  entry?: null | IntersectionObserverEntry;
 
-    /**
-     * `IntersectionObserver` instance.
-     * @default null
-     */
-    observer?: null | IntersectionObserver;
-  },
-  {
-    /**
-     * Dispatched when the element is first observed
-     * and also whenever an intersection event occurs.
-     */
-    observe: CustomEvent<IntersectionObserverEntry>;
+  /**
+   * `IntersectionObserver` instance.
+   * @default null
+   */
+  observer?: null | IntersectionObserver;
 
-    /**
-     * Dispatched only when the element is intersecting the viewport.
-     * `event.detail.isIntersecting` will only be `true`
-     */
-    intersect: CustomEvent<
-      IntersectionObserverEntry & { isIntersecting: true }
-    >;
-  },
-  {
-    default: {
-      intersecting: boolean;
-      entry: null | IntersectionObserverEntry;
-      observer: IntersectionObserver;
-    };
-  }
-> {}
+  /**
+   * Set to `true` to pause observing without disconnecting the
+   * observer or losing `entry`/`intersecting` state. Set back to
+   * `false` to resume.
+   * @default false
+   */
+  skip?: boolean;
+
+  /**
+   * Called when the element is first observed
+   * and also whenever an intersection event occurs.
+   */
+  onobserve?: (entry: IntersectionObserverEntry) => void;
+
+  /**
+   * Called only when the element is intersecting the viewport.
+   * `entry.isIntersecting` will always be `true`.
+   */
+  onintersect?: (
+    entry: IntersectionObserverEntry & { isIntersecting: true },
+  ) => void;
+
+  children?: Snippet<
+    [
+      {
+        intersecting: boolean;
+        entry: null | IntersectionObserverEntry;
+        observer: null | IntersectionObserver;
+      },
+    ]
+  >;
+}
+
+declare const IntersectionObserverComponent: Component<
+  IntersectionObserverProps,
+  Record<string, never>,
+  "intersecting" | "entry" | "observer"
+>;
+
+export default IntersectionObserverComponent;

package/MultipleIntersectionObserver.svelte

@@ -1,139 +1,115 @@
 <script>
-  /**
-   * Array of HTML Elements to observe.
-   * Use this for better performance when observing multiple elements.
-   * @type {(HTMLElement | null)[]}
-   */
-  export let elements = [];
-
-  /**
-   * Set to `true` to unobserve the element
-   * after it intersects the viewport.
-   * @type {boolean}
-   */
-  export let once = false;
-
-  /**
-   * Specify the containing element.
-   * Defaults to the browser viewport.
-   * @type {null | HTMLElement}
-   */
-  export let root = null;
-
-  /** Margin offset of the containing element. */
-  export let rootMargin = "0px";
+  import { untrack } from "svelte";
 
   /**
-   * Percentage of element visibility to trigger an event.
-   * Value must be between 0 and 1.
+   * @typedef {Object} Props
+   * @property {(HTMLElement | null)[]} [elements] Array of HTML Elements to observe. Use this for better performance when observing multiple elements.
+   * @property {boolean} [once] Set to `true` to unobserve the element after it intersects the viewport.
+   * @property {null | HTMLElement} [root] Specify the containing element. Defaults to the browser viewport.
+   * @property {string} [rootMargin] Margin offset of the containing element.
+   * @property {number | number[]} [threshold] Percentage of element visibility to trigger an event. Value must be between 0 and 1.
+   * @property {Map<HTMLElement | null, boolean>} [elementIntersections] Map of element to its intersection state.
+   * @property {Map<HTMLElement | null, IntersectionObserverEntry>} [elementEntries] Map of element to its latest entry.
+   * @property {null | IntersectionObserver} [observer] `IntersectionObserver` instance.
+   * @property {boolean} [skip] Set to `true` to pause observing all elements without disconnecting the observer or losing `elementIntersections`/`elementEntries` state. Set back to `false` to resume.
+   * @property {(detail: { entry: IntersectionObserverEntry, target: HTMLElement }) => void} [onobserve] Called when an element is first observed and also whenever an intersection event occurs.
+   * @property {(detail: { entry: IntersectionObserverEntry & { isIntersecting: true }, target: HTMLElement }) => void} [onintersect] Called only when an element is intersecting the viewport.
+   * @property {import("svelte").Snippet<[{ observer: null | IntersectionObserver, elementIntersections: Map<HTMLElement | null, boolean>, elementEntries: Map<HTMLElement | null, IntersectionObserverEntry> }]>} [children]
    */
-  export let threshold = 0;
 
-  /**
-   * Map of element to its intersection state.
-   * @type {Map<HTMLElement | null, boolean>}
-   */
-  export let elementIntersections = new Map();
-
-  /**
-   * Map of element to its latest entry.
-   * @type {Map<HTMLElement | null, IntersectionObserverEntry>}
-   */
-  export let elementEntries = new Map();
-
-  /**
-   * `IntersectionObserver` instance.
-   * @type {null | IntersectionObserver}
-   */
-  export let observer = null;
-
-  import { tick, createEventDispatcher, afterUpdate, onMount } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  let prevRootMargin = rootMargin;
-
-  let prevThreshold = threshold;
-
-  /** @type {null | HTMLElement} */
-  let prevRoot = root;
+  /** @type {Props} */
+  let {
+    elements = [],
+    once = false,
+    root = null,
+    rootMargin = "0px",
+    threshold = 0,
+    elementIntersections = $bindable(new Map()),
+    elementEntries = $bindable(new Map()),
+    observer = $bindable(null),
+    skip = false,
+    onobserve,
+    onintersect,
+    children,
+  } = $props();
 
   /** @type {(HTMLElement | null)[]} */
   let prevElements = [];
 
+  let prevSkip = untrack(() => skip);
+
   const initialize = () => {
     observer = new IntersectionObserver(
       (entries) => {
-        entries.forEach((_entry) => {
+        for (const _entry of entries) {
           const target = /** @type {HTMLElement} */ (_entry.target);
 
           elementIntersections.set(target, _entry.isIntersecting);
           elementEntries.set(target, _entry);
 
-          // Trigger reactivity.
-          elementIntersections = new Map(elementIntersections);
-          elementEntries = new Map(elementEntries);
-
-          dispatch("observe", { entry: _entry, target });
+          onobserve?.({ entry: _entry, target });
 
           if (_entry.isIntersecting) {
-            dispatch("intersect", { entry: _entry, target });
+            onintersect?.({ entry: _entry, target });
             if (once) observer?.unobserve(target);
           }
-        });
+        }
+
+        // Trigger reactivity once per batch, not once per entry.
+        elementIntersections = new Map(elementIntersections);
+        elementEntries = new Map(elementEntries);
       },
       { root, rootMargin, threshold },
     );
   };
 
-  onMount(() => {
+  $effect(() => {
+    prevElements = [];
     initialize();
 
     return () => {
-      if (observer) {
-        observer.disconnect();
-        observer = null;
-      }
+      observer?.disconnect();
+      observer = null;
     };
   });
 
-  afterUpdate(async () => {
-    await tick();
+  $effect(() => {
+    const currentElements = elements;
+    const isSkipped = skip;
+    const activeObserver = observer;
 
-    if (elements.length > 0) {
-      const newElements = elements.filter(
+    if (currentElements.length > 0) {
+      const newElements = currentElements.filter(
         (el) => el && !prevElements.includes(el),
       );
-      newElements.forEach((el) => {
-        if (el) observer?.observe(el);
-      });
+
+      if (!isSkipped) {
+        for (const el of newElements) {
+          if (el) activeObserver?.observe(el);
+        }
+      }
 
       const removedElements = prevElements.filter(
-        (el) => el && !elements.includes(el),
+        (el) => el && !currentElements.includes(el),
       );
-      removedElements.forEach((el) => {
-        if (el) observer?.unobserve(el);
-      });
 
-      prevElements = [...elements];
+      for (const el of removedElements) {
+        if (el) activeObserver?.unobserve(el);
+      }
+
+      prevElements = [...currentElements];
     }
 
-    if (rootMargin !== prevRootMargin || threshold !== prevThreshold || root !== prevRoot) {
-      observer?.disconnect();
-      prevElements = [];
-      initialize();
-
-      elements
-        .filter((el) => el)
-        .forEach((el) => {
-          if (el) observer?.observe(el);
-        });
+    if (isSkipped !== prevSkip) {
+      for (const el of currentElements) {
+        if (!el) continue;
+        if (isSkipped) activeObserver?.unobserve(el);
+        else activeObserver?.observe(el);
+      }
     }
 
-    prevRootMargin = rootMargin;
-    prevThreshold = threshold;
-    prevRoot = root;
+    prevSkip = isSkipped;
   });
 </script>
 
-<slot {observer} {elementIntersections} {elementEntries} />
+{@render children?.({ observer, elementIntersections, elementEntries })}

package/MultipleIntersectionObserver.svelte.d.ts

@@ -1,82 +1,98 @@
-import type { SvelteComponentTyped } from "svelte";
+import type { Component, Snippet } from "svelte";
 
-export default class extends SvelteComponentTyped<
-  {
-    /**
-     * Array of HTML Elements to observe.
-     * Use this for better performance when observing multiple elements.
-     * @default []
-     */
-    elements?: (HTMLElement | null)[];
+export interface MultipleIntersectionObserverProps {
+  /**
+   * Array of HTML Elements to observe.
+   * Use this for better performance when observing multiple elements.
+   * @default []
+   */
+  elements?: (HTMLElement | null)[];
 
-    /**
-     * Set to `true` to unobserve the element
-     * after it intersects the viewport.
-     * @default false
-     */
-    once?: boolean;
+  /**
+   * Set to `true` to unobserve the element
+   * after it intersects the viewport.
+   * @default false
+   */
+  once?: boolean;
 
-    /**
-     * Specify the containing element.
-     * Defaults to the browser viewport.
-     * @default null
-     */
-    root?: null | HTMLElement;
+  /**
+   * Specify the containing element.
+   * Defaults to the browser viewport.
+   * @default null
+   */
+  root?: null | HTMLElement;
 
-    /**
-     * Margin offset of the containing element.
-     * @default "0px"
-     */
-    rootMargin?: string;
+  /**
+   * Margin offset of the containing element.
+   * @default "0px"
+   */
+  rootMargin?: string;
 
-    /**
-     * Percentage of element visibility to trigger an event.
-     * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
-     * @default 0
-     */
-    threshold?: number | number[];
+  /**
+   * Percentage of element visibility to trigger an event.
+   * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
+   * @default 0
+   */
+  threshold?: number | number[];
 
-    /**
-     * Map of element to its intersection state.
-     * @default new Map()
-     */
-    elementIntersections?: Map<HTMLElement | null, boolean>;
+  /**
+   * Map of element to its intersection state.
+   * @default new Map()
+   */
+  elementIntersections?: Map<HTMLElement | null, boolean>;
 
-    /**
-     * Map of element to its latest entry.
-     * @default new Map()
-     */
-    elementEntries?: Map<HTMLElement | null, IntersectionObserverEntry>;
+  /**
+   * Map of element to its latest entry.
+   * @default new Map()
+   */
+  elementEntries?: Map<HTMLElement | null, IntersectionObserverEntry>;
 
-    /**
-     * `IntersectionObserver` instance.
-     * @default null
-     */
-    observer?: null | IntersectionObserver;
-  },
-  {
-    /**
-     * Dispatched when an element is first observed
-     * and also whenever an intersection event occurs.
-     */
-    observe: CustomEvent<{
-      entry: IntersectionObserverEntry;
-      target: HTMLElement;
-    }>;
+  /**
+   * `IntersectionObserver` instance.
+   * @default null
+   */
+  observer?: null | IntersectionObserver;
 
-    /**
-     * Dispatched only when an element is intersecting the viewport.
-     */
-    intersect: CustomEvent<{
-      entry: IntersectionObserverEntry & { isIntersecting: true };
-      target: HTMLElement;
-    }>;
-  },
-  {
-    default: {
-      observer: IntersectionObserver;
-      elementIntersections: Map<HTMLElement | null, boolean>;
-      elementEntries: Map<HTMLElement | null, IntersectionObserverEntry>;
-    };
-  }
-> {}
+  /**
+   * Set to `true` to pause observing all elements without disconnecting
+   * the observer or losing `elementIntersections`/`elementEntries` state.
+   * Set back to `false` to resume.
+   * @default false
+   */
+  skip?: boolean;
+
+  /**
+   * Called when an element is first observed
+   * and also whenever an intersection event occurs.
+   */
+  onobserve?: (detail: {
+    entry: IntersectionObserverEntry;
+    target: HTMLElement;
+  }) => void;
+
+  /**
+   * Called only when an element is intersecting the viewport.
+   */
+  onintersect?: (detail: {
+    entry: IntersectionObserverEntry & { isIntersecting: true };
+    target: HTMLElement;
+  }) => void;
+
+  children?: Snippet<
+    [
+      {
+        observer: null | IntersectionObserver;
+        elementIntersections: Map<HTMLElement | null, boolean>;
+        elementEntries: Map<HTMLElement | null, IntersectionObserverEntry>;
+      },
+    ]
+  >;
+}
+
+declare const MultipleIntersectionObserverComponent: Component<
+  MultipleIntersectionObserverProps,
+  Record<string, never>,
+  "elementIntersections" | "elementEntries" | "observer"
+>;
+
+export default MultipleIntersectionObserverComponent;

package/README.md

@@ -4,10 +4,19 @@
 
 > Detect if an element is in the viewport using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
 
-<!-- REPO_URL -->
+Use it to lazy-load images, trigger scroll animations, implement infinite scroll, autoplay video when visible, track ad or analytics impressions, or detect when a user has scrolled to the end of a list.
+
+This library is zero-dependency and offers three ways to observe elements: the `IntersectionObserver` component for a single element, the `MultipleIntersectionObserver` component for observing many elements with one shared observer (better performance than one observer per element), and the `intersect` action for observing an element directly with `use:`.
 
 Try it in the [Svelte REPL](https://svelte.dev/repl/8cd2327a580c4f429c71f7df999bd51d).
 
+## Compatibility
+
+| Package version | Svelte version    | Notes                                     |
+| :--------------- | :----------------- | :----------------------------------------- |
+| 1.x              | 3, 4, 5 (non-runes) | Uses `export let`, slots, and `on:` events |
+| 2.x              | 5 (runes mode only) | Uses `$props()`, snippets, and callback props |
+
 <!-- TOC -->
 
 ## Installation
@@ -39,8 +48,8 @@ Then, simply bind to the reactive `intersecting` prop to determine if the elemen
 <script>
   import IntersectionObserver from "svelte-intersection-observer";
 
-  let element;
-  let intersecting;
+  let element = $state();
+  let intersecting = $state(false);
 </script>
 
 <header class:intersecting>
@@ -52,6 +61,33 @@ Then, simply bind to the reactive `intersecting` prop to determine if the elemen
 </IntersectionObserver>
 ```
 
+### `children` snippet
+
+An alternative to binding to the `intersecting` prop is to use the `children` snippet, which receives `intersecting`, `entry`, and `observer`.
+
+In the following example, the "Hello world" element fades in when its containing element intersects the viewport.
+
+```svelte
+<script>
+  import IntersectionObserver from "svelte-intersection-observer";
+  import { fade } from "svelte/transition";
+
+  let node = $state();
+</script>
+
+<header></header>
+
+<IntersectionObserver element={node}>
+  {#snippet children({ intersecting })}
+    <div bind:this={node}>
+      {#if intersecting}
+        <div transition:fade={{ delay: 200 }}>Hello world</div>
+      {/if}
+    </div>
+  {/snippet}
+</IntersectionObserver>
+```
+
 ### Once
 
 Set `once` to `true` for the intersection event to occur only once. The `element` will be unobserved after the first intersection event occurs.
@@ -60,8 +96,8 @@ Set `once` to `true` for the intersection event to occur only once. The `element
 <script>
   import IntersectionObserver from "svelte-intersection-observer";
 
-  let elementOnce;
-  let intersectOnce;
+  let elementOnce = $state();
+  let intersectOnce = $state(false);
 </script>
 
 <header class:intersecting={intersectOnce}>
@@ -77,96 +113,237 @@ Set `once` to `true` for the intersection event to occur only once. The `element
 </IntersectionObserver>
 ```
 
-### `let:intersecting`
-
-An alternative to binding to the `intersecting` prop is to use the `let:` directive.
+### Pausing with `skip`
 
-In the following example, the "Hello world" element will fade in when its containing element intersects the viewport.
+Set `skip` to `true` to unobserve without disconnecting the underlying observer or losing `entry`/`intersecting` state. This is useful for pausing tracking on an off-screen carousel panel or a closed modal. Set `skip` back to `false` to resume; unlike `once`, this can be toggled back and forth. `MultipleIntersectionObserver` and the `intersect` action support the same `skip` option.
 
-```svelte
+```svelte no-eval
 <script>
   import IntersectionObserver from "svelte-intersection-observer";
-  import { fade } from "svelte/transition";
 
-  let node;
+  let elementSkip = $state();
+  let paused = $state(false);
 </script>
 
-<header />
+<button onclick={() => (paused = !paused)}>
+  {paused ? "Resume" : "Pause"}
+</button>
 
-<IntersectionObserver element={node} let:intersecting>
-  <div bind:this={node}>
-    {#if intersecting}
-      <div transition:fade={{ delay: 200 }}>Hello world</div>
-    {/if}
-  </div>
+<IntersectionObserver element={elementSkip} skip={paused}>
+  {#snippet children({ intersecting })}
+    <div bind:this={elementSkip}>{intersecting ? "In view" : "Not in view"}</div>
+  {/snippet}
 </IntersectionObserver>
 ```
 
-### `on:observe` event
+### `onobserve` callback prop
 
-The `observe` event is dispatched when the element is first observed and also whenever an intersection event occurs.
+`onobserve` is called when the element is first observed and also whenever an intersection event occurs.
 
 ```svelte no-eval
 <IntersectionObserver
   {element}
-  on:observe={(e) => {
-    console.log(e.detail); // IntersectionObserverEntry
-    console.log(e.detail.isIntersecting); // true | false
+  onobserve={(entry) => {
+    console.log(entry); // IntersectionObserverEntry
+    console.log(entry.isIntersecting); // true | false
   }}
 >
   <div bind:this={element}>Hello world</div>
 </IntersectionObserver>
 ```
 
-### `on:intersect` event
+### `onintersect` callback prop
 
-As an alternative to binding the `intersecting` prop, you can listen to the `intersect` event that is dispatched if the observed element is intersecting the viewport.
+As an alternative to binding the `intersecting` prop, you can pass an `onintersect` callback that is called if the observed element is intersecting the viewport.
 
-**Note**: Compared to `on:observe`, `on:intersect` is dispatched only when the element is _intersecting the viewport_. In other words, `e.detail.isIntersecting` will only be `true`.
+**Note**: Compared to `onobserve`, `onintersect` is called only when the element is _intersecting the viewport_. In other words, `entry.isIntersecting` will only be `true`.
 
 ```svelte no-eval
 <IntersectionObserver
   {element}
-  on:intersect={(e) => {
-    console.log(e.detail); // IntersectionObserverEntry
-    console.log(e.detail.isIntersecting); // true
+  onintersect={(entry) => {
+    console.log(entry); // IntersectionObserverEntry
+    console.log(entry.isIntersecting); // true
   }}
 >
   <div bind:this={element}>Hello world</div>
 </IntersectionObserver>
 ```
 
+### Detecting scroll to end
+
+To detect when a user has scrolled to the end of a scrollable container, place a sentinel element after the content and set `root` to the container. `intersecting` becomes `true` once the sentinel scrolls into view.
+
+**Note**: `root` must be the scrollable element itself (i.e. it has its own `overflow`/fixed `height`), not just an ancestor of one. If `root` merely sits inside a scrollable ancestor, the sentinel scrolls along with `root` and never changes position relative to it, so it reports as permanently intersecting.
+
+```svelte
+<script>
+  import IntersectionObserver from "svelte-intersection-observer";
+
+  let container = $state();
+  let sentinel = $state();
+  let reachedEnd = $state(false);
+</script>
+
+<header class:intersecting={reachedEnd}>
+  {reachedEnd ? "You've reached the end" : "Keep scrolling..."}
+</header>
+
+<div bind:this={container} style="height: 200px; overflow-y: auto;">
+  {#each Array.from({ length: 20 }) as _, i}
+    <p>Paragraph {i + 1}</p>
+  {/each}
+
+  <IntersectionObserver
+    element={sentinel}
+    root={container}
+    bind:intersecting={reachedEnd}
+  >
+    <div bind:this={sentinel} style="height: 1px;"></div>
+  </IntersectionObserver>
+</div>
+```
+
+### Scrolling to a conditionally revealed element
+
+Keep the `bind:this` element outside the `{#if intersecting}` block, and only gate the animated content inside it. The bound element then stays in the DOM, so you can call `scrollIntoView()` on it whenever you want, whether or not its reveal animation has played yet.
+
+```svelte
+<script>
+  import IntersectionObserver from "svelte-intersection-observer";
+  import { fly } from "svelte/transition";
+
+  let revealNode = $state();
+  let revealIntersecting = $state(false);
+</script>
+
+<header class:intersecting={revealIntersecting}>
+  <button
+    onclick={() => {
+      revealNode.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    }}
+  >
+    Scroll to section
+  </button>
+</header>
+
+<IntersectionObserver element={revealNode} once bind:intersecting={revealIntersecting}>
+  <div bind:this={revealNode}>
+    {#if revealIntersecting}
+      <section transition:fly={{ y: 50, delay: 200, duration: 300 }}>
+        Hello world
+      </section>
+    {/if}
+  </div>
+</IntersectionObserver>
+```
+
+### `use:intersect` action
+
+As an alternative to the `IntersectionObserver` component, use the `intersect` action to observe an element directly with `use:`, without a `bind:this` reference or wrapper markup. Listen for `onobserve`/`onintersect` on the observed element itself.
+
+```svelte
+<script>
+  import { intersect } from "svelte-intersection-observer";
+
+  let actionIntersecting = $state(false);
+</script>
+
+<header class:intersecting={actionIntersecting}>
+  {actionIntersecting ? "Element is in view" : "Element is not in view"}
+</header>
+
+<div
+  use:intersect={{ once: true }}
+  onobserve={(e) => (actionIntersecting = e.detail.isIntersecting)}
+>
+  Hello world
+</div>
+```
+
+Options passed to `use:intersect` are reactive: updating `root`, `rootMargin`, or `threshold` re-initializes the underlying observer. Updating `skip` toggles observing on the existing observer without re-initializing it.
+
 ### Multiple elements
 
-For performance, use `MultipleIntersectionObserver` to observe multiple elements.
+For performance, use `MultipleIntersectionObserver` to observe multiple elements with a single shared observer instead of instantiating a new one for every element.
+
+```svelte
+<script>
+  import { MultipleIntersectionObserver } from "svelte-intersection-observer";
+
+  let ref1 = $state();
+  let ref2 = $state();
+
+  let elements = $derived([ref1, ref2]);
+</script>
+
+<MultipleIntersectionObserver {elements}>
+  {#snippet children({ elementIntersections })}
+    <header>
+      <div class:intersecting={elementIntersections.get(ref1)}>
+        Item 1: {elementIntersections.get(ref1) ? "✓" : "✗"}
+      </div>
+      <div class:intersecting={elementIntersections.get(ref2)}>
+        Item 2: {elementIntersections.get(ref2) ? "✓" : "✗"}
+      </div>
+    </header>
+
+    <div bind:this={ref1}>Item 1</div>
+    <div bind:this={ref2}>Item 2</div>
+  {/snippet}
+</MultipleIntersectionObserver>
+```
+
+### Using with `#each`
 
-This avoids instantiating a new observer for every element.
+`MultipleIntersectionObserver` also handles a dynamic, `#each`-driven list: give every item its own slot in an array/object instead of one shared variable.
 
 ```svelte
 <script>
   import { MultipleIntersectionObserver } from "svelte-intersection-observer";
 
-  let ref1;
-  let ref2;
+  let items = Array.from({ length: 10 }, (_, i) => ({
+    id: i + 1,
+    text: `Item ${i + 1}`,
+  }));
 
-  $: elements = [ref1, ref2];
+  let refs = $state([]);
+  let itemsContainer = $state();
+
+  let itemElements = $derived(refs);
 </script>
 
-<MultipleIntersectionObserver {elements} let:elementIntersections>
-  <header>
-    <div class:intersecting={elementIntersections.get(ref1)}>
-      Item 1: {elementIntersections.get(ref1) ? "✓" : "✗"}
-    </div>
-    <div class:intersecting={elementIntersections.get(ref2)}>
-      Item 2: {elementIntersections.get(ref2) ? "✓" : "✗"}
+<MultipleIntersectionObserver elements={itemElements} root={itemsContainer}>
+  {#snippet children({ elementIntersections })}
+    <header>
+      {#each items as item, i (item.id)}
+        <div class:intersecting={elementIntersections.get(refs[i])}>
+          {item.text}: {elementIntersections.get(refs[i]) ? "✓" : "✗"}
+        </div>
+      {/each}
+    </header>
+
+    <div
+      bind:this={itemsContainer}
+      style="height: 150px; overflow-y: auto; display: flex; flex-direction: column; gap: 1rem;"
+    >
+      {#each items as item, i (item.id)}
+        <div
+          bind:this={refs[i]}
+          style="height: 100px; display: flex; align-items: center; flex-shrink: 0;"
+        >
+          {item.text}
+        </div>
+      {/each}
     </div>
-  </header>
-
-  <div bind:this={ref1}>Item 1</div>
-  <div bind:this={ref2}>Item 2</div>
+  {/snippet}
 </MultipleIntersectionObserver>
 ```
 
+As with the scroll-to-end example, `root` must be an element that scrolls on its own; here, `itemsContainer` has an explicit `height` and `overflow-y: auto`.
+
+**Avoid** using the single-element `IntersectionObserver` component inside an `#each` block with one variable shared across iterations (e.g. `let node;` declared outside the loop and bound via `bind:this={node}` inside it). Every iteration overwrites the same `node`, so each observer instance keeps re-observing a moving target, which can produce an infinite update loop. Use `MultipleIntersectionObserver` with a per-item ref, as shown above, instead.
+
 ## API
 
 ### IntersectionObserver
@@ -183,15 +360,18 @@ This avoids instantiating a new observer for every element.
 | threshold    | Percentage of element visibility to trigger an event        | `number` between 0 and 1, or an array of `number`s between 0 and 1                                                  | `0`           |
 | entry        | Observed element metadata                                   | `null` or [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) | `null`        |
 | observer     | `IntersectionObserver` instance                             | `null` or [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)           | `null`        |
+| skip         | Pause observing without losing `entry`/`intersecting` state | `boolean`                                                                                                           | `false`       |
 
-#### Dispatched events
+**Note**: the observed `element` must render with a non-zero width and height for `threshold` values greater than `0` to have any effect. This is a constraint of the underlying [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API), not something this component controls.
 
-- **on:observe**: fired when the element is first observed or whenever an intersection change occurs
-- **on:intersect**: fired when the element is intersecting the viewport
+#### Callback props
 
-The `e.detail` dispatched by the `observe` and `intersect` events is an [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) interface.
+- **onobserve**: called when the element is first observed or whenever an intersection change occurs
+- **onintersect**: called when the element is intersecting the viewport
+
+Both callbacks are called with an [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry).
 
-#### Slot props
+#### `children` snippet props
 
 | Name         | Type                                                                                                                |
 | :----------- | :------------------------------------------------------------------------------------------------------------------ |
@@ -213,13 +393,14 @@ The `e.detail` dispatched by the `observe` and `intersect` events is an [`Inters
 | elementIntersections | Map of each element to its intersection state         | `Map<HTMLElement \| null, boolean>`                                                                                                     | `new Map()`   |
 | elementEntries       | Map of each element to its latest entry               | `Map<HTMLElement \| null,` [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)`>` | `new Map()`   |
 | observer             | `IntersectionObserver` instance                       | `null` or [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)                               | `null`        |
+| skip                 | Pause observing all elements without losing state     | `boolean`                                                                                                                               | `false`       |
 
-#### Dispatched events
+#### Callback props
 
-- **on:observe**: fired when an element is first observed or whenever an intersection change occurs
-- **on:intersect**: fired when an element is intersecting the viewport
+- **onobserve**: called when an element is first observed or whenever an intersection change occurs
+- **onintersect**: called when an element is intersecting the viewport
 
-The `e.detail` for both events includes:
+Both callbacks are called with:
 
 ```ts
 {
@@ -228,7 +409,7 @@ The `e.detail` for both events includes:
 }
 ```
 
-#### Slot props
+#### `children` snippet props
 
 | Name                 | Type                                                                                                                                    |
 | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
@@ -236,6 +417,25 @@ The `e.detail` for both events includes:
 | elementIntersections | `Map<HTMLElement \| null, boolean>`                                                                                                     |
 | elementEntries       | `Map<HTMLElement \| null,` [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)`>` |
 
+### `intersect` action
+
+#### Options
+
+| Name       | Description                                              | Type                                                               | Default value |
+| :--------- | :------------------------------------------------------- | :----------------------------------------------------------------- | :------------ |
+| root       | Containing element                                       | `null` or `HTMLElement`                                            | `null`        |
+| rootMargin | Margin offset of the containing element                  | `string`                                                           | `"0px"`       |
+| threshold  | Percentage of element visibility to trigger an event     | `number` between 0 and 1, or an array of `number`s between 0 and 1 | `0`           |
+| once       | Unobserve the element after the first intersection event | `boolean`                                                          | `false`       |
+| skip       | Pause observing without disconnecting the observer       | `boolean`                                                          | `false`       |
+
+#### Dispatched events
+
+- **onobserve**: fired on the element when it is first observed or whenever an intersection change occurs
+- **onintersect**: fired on the element when it is intersecting the viewport
+
+The `e.detail` dispatched by the `observe` and `intersect` events is an [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) interface.
+
 ### `IntersectionObserverEntry` interface
 
 Note that all properties in [IntersectionObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) are read-only.
@@ -285,13 +485,5 @@ interface IntersectionObserverEntry {
 
 </details>
 
-## Changelog
-
-[Changelog](CHANGELOG.md)
-
-## License
-
-[MIT](LICENSE)
-
 [npm]: https://img.shields.io/npm/v/svelte-intersection-observer.svg?color=%23ff3e00&style=for-the-badge
 [npm-url]: https://npmjs.com/package/svelte-intersection-observer

package/index.d.ts

@@ -1,2 +1,4 @@
 export { default } from "./IntersectionObserver.svelte";
+export type { IntersectActionOptions } from "./intersect.svelte.js";
+export { intersect } from "./intersect.svelte.js";
 export { default as MultipleIntersectionObserver } from "./MultipleIntersectionObserver.svelte";

package/index.js

@@ -1,2 +1,3 @@
 export { default } from "./IntersectionObserver.svelte";
+export { intersect } from "./intersect.svelte.js";
 export { default as MultipleIntersectionObserver } from "./MultipleIntersectionObserver.svelte";

package/intersect.svelte.d.ts

@@ -0,0 +1,53 @@
+import type { Action } from "svelte/action";
+
+export interface IntersectActionOptions {
+  /**
+   * Specify the containing element.
+   * Defaults to the browser viewport.
+   * @default null
+   */
+  root?: null | HTMLElement;
+
+  /**
+   * Margin offset of the containing element.
+   * @default "0px"
+   */
+  rootMargin?: string;
+
+  /**
+   * Percentage of element visibility to trigger an event.
+   * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
+   * @default 0
+   */
+  threshold?: number | number[];
+
+  /**
+   * Set to `true` to unobserve the element
+   * after it intersects the viewport.
+   * @default false
+   */
+  once?: boolean;
+
+  /**
+   * Set to `true` to pause observing without disconnecting the
+   * observer. Set back to `false` to resume.
+   * @default false
+   */
+  skip?: boolean;
+}
+
+/**
+ * Svelte action that observes the element with the Intersection Observer API.
+ * Dispatches `observe` (on every change) and `intersect` (on entering the
+ * viewport) `CustomEvent`s on the element — listen with `onobserve`/`onintersect`.
+ */
+export const intersect: Action<
+  HTMLElement,
+  IntersectActionOptions | undefined,
+  {
+    onobserve?: (event: CustomEvent<IntersectionObserverEntry>) => void;
+    onintersect?: (
+      event: CustomEvent<IntersectionObserverEntry & { isIntersecting: true }>,
+    ) => void;
+  }
+>;

package/intersect.svelte.js

@@ -0,0 +1,69 @@
+/**
+ * Svelte action that observes `node` with the Intersection Observer API.
+ * Dispatches `observe` (on every change) and `intersect` (on entering the
+ * viewport) `CustomEvent`s on `node` — listen with `onobserve`/`onintersect`.
+ * @param {HTMLElement} node
+ * @param {import("./intersect.svelte.d.ts").IntersectActionOptions} [options]
+ */
+export function intersect(node, options = {}) {
+  let {
+    root = null,
+    rootMargin = "0px",
+    threshold = 0,
+    once = false,
+    skip = false,
+  } = options;
+
+  /** @type {IntersectionObserver} */
+  let observer;
+
+  const createObserver = () =>
+    new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          node.dispatchEvent(new CustomEvent("observe", { detail: entry }));
+
+          if (entry.isIntersecting) {
+            node.dispatchEvent(new CustomEvent("intersect", { detail: entry }));
+            if (once) observer.unobserve(node);
+          }
+        }
+      },
+      { root, rootMargin, threshold },
+    );
+
+  observer = createObserver();
+  if (!skip) observer.observe(node);
+
+  return {
+    /** @param {import("./intersect.svelte.d.ts").IntersectActionOptions} [newOptions] */
+    update(newOptions = {}) {
+      once = newOptions.once ?? false;
+
+      const newSkip = newOptions.skip ?? false;
+
+      const configChanged =
+        (newOptions.root ?? null) !== root ||
+        (newOptions.rootMargin ?? "0px") !== rootMargin ||
+        JSON.stringify(newOptions.threshold ?? 0) !== JSON.stringify(threshold);
+
+      if (configChanged) {
+        root = newOptions.root ?? null;
+        rootMargin = newOptions.rootMargin ?? "0px";
+        threshold = newOptions.threshold ?? 0;
+
+        observer.disconnect();
+        observer = createObserver();
+        if (!newSkip) observer.observe(node);
+      } else if (newSkip !== skip) {
+        if (newSkip) observer.unobserve(node);
+        else observer.observe(node);
+      }
+
+      skip = newSkip;
+    },
+    destroy() {
+      observer.disconnect();
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-intersection-observer",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "license": "MIT",
   "description": "Detect if an element is in the viewport using the Intersection Observer API",
   "author": "Eric Liu (https://github.com/metonym)",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/metonym/svelte-intersection-observer.git"
   },
-  "homepage": "https://github.com/metonym/svelte-intersection-observer",
+  "homepage": "https://metonym.github.io/svelte-intersection-observer/",
   "bugs": "https://github.com/metonym/svelte-intersection-observer/issues",
   "keywords": [
     "svelte",