svelte-intersection-observer 1.1.2 → 1.2.0

package/IntersectionObserver.svelte

@@ -46,7 +46,15 @@
    */
   export let observer = null;
 
-  import { tick, createEventDispatcher, afterUpdate, onMount } from "svelte";
+  /**
+   * Set to `true` to pause observing without disconnecting the
+   * observer or losing `entry`/`intersecting` state. Set back to
+   * `false` to resume.
+   * @type {boolean}
+   */
+  export let skip = false;
+
+  import { afterUpdate, createEventDispatcher, onMount, tick } from "svelte";
 
   const dispatch = createEventDispatcher();
 
@@ -60,10 +68,12 @@
   /** @type {null | HTMLElement} */
   let prevElement = null;
 
+  let prevSkip = skip;
+
   const initialize = () => {
     observer = new IntersectionObserver(
       (entries) => {
-        entries.forEach((_entry) => {
+        for (const _entry of entries) {
           entry = _entry;
           intersecting = _entry.isIntersecting;
 
@@ -74,7 +84,7 @@
 
             if (element && once) observer?.unobserve(element);
           }
-        });
+        }
       },
       { root, rootMargin, threshold },
     );
@@ -95,22 +105,38 @@
     await tick();
 
     if (element !== null && element !== prevElement) {
-      observer?.observe(element);
+      if (!skip) observer?.observe(element);
 
       if (prevElement !== null) observer?.unobserve(prevElement);
       prevElement = element;
     }
 
-    if (rootMargin !== prevRootMargin || threshold !== prevThreshold || root !== prevRoot) {
+    if (skip !== prevSkip && element !== null) {
+      if (skip) observer?.unobserve(element);
+      else observer?.observe(element);
+    }
+
+    if (
+      rootMargin !== prevRootMargin ||
+      threshold !== prevThreshold ||
+      root !== prevRoot
+    ) {
       observer?.disconnect();
-      prevElement = null;
       initialize();
+
+      if (element !== null && !skip) observer?.observe(element);
+      prevElement = element;
     }
 
     prevRootMargin = rootMargin;
     prevThreshold = threshold;
     prevRoot = root;
+    prevSkip = skip;
   });
 </script>
 
-<slot {intersecting} {entry} {observer} />
+<slot
+  {intersecting}
+  {entry}
+  {observer}
+/>

package/IntersectionObserver.svelte.d.ts

@@ -53,6 +53,14 @@ export default class extends SvelteComponentTyped<
      * @default null
      */
     observer?: null | 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;
   },
   {
     /**

package/MultipleIntersectionObserver.svelte

@@ -47,7 +47,15 @@
    */
   export let observer = null;
 
-  import { tick, createEventDispatcher, afterUpdate, onMount } from "svelte";
+  /**
+   * Set to `true` to pause observing all elements without disconnecting
+   * the observer or losing `elementIntersections`/`elementEntries` state.
+   * Set back to `false` to resume.
+   * @type {boolean}
+   */
+  export let skip = false;
+
+  import { afterUpdate, createEventDispatcher, onMount, tick } from "svelte";
 
   const dispatch = createEventDispatcher();
 
@@ -61,26 +69,28 @@
   /** @type {(HTMLElement | null)[]} */
   let prevElements = [];
 
+  let prevSkip = 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 });
 
           if (_entry.isIntersecting) {
             dispatch("intersect", { 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 },
     );
@@ -104,36 +114,55 @@
       const newElements = elements.filter(
         (el) => el && !prevElements.includes(el),
       );
-      newElements.forEach((el) => {
-        if (el) observer?.observe(el);
-      });
+      if (!skip) {
+        for (const el of newElements) {
+          if (el) observer?.observe(el);
+        }
+      }
 
       const removedElements = prevElements.filter(
         (el) => el && !elements.includes(el),
       );
-      removedElements.forEach((el) => {
+      for (const el of removedElements) {
         if (el) observer?.unobserve(el);
-      });
+      }
 
       prevElements = [...elements];
     }
 
-    if (rootMargin !== prevRootMargin || threshold !== prevThreshold || root !== prevRoot) {
+    if (skip !== prevSkip) {
+      for (const el of elements.filter((el) => el)) {
+        if (!el) continue;
+        if (skip) observer?.unobserve(el);
+        else observer?.observe(el);
+      }
+    }
+
+    if (
+      rootMargin !== prevRootMargin ||
+      threshold !== prevThreshold ||
+      root !== prevRoot
+    ) {
       observer?.disconnect();
       prevElements = [];
       initialize();
 
-      elements
-        .filter((el) => el)
-        .forEach((el) => {
+      if (!skip) {
+        for (const el of elements.filter((el) => el)) {
           if (el) observer?.observe(el);
-        });
+        }
+      }
     }
 
     prevRootMargin = rootMargin;
     prevThreshold = threshold;
     prevRoot = root;
+    prevSkip = skip;
   });
 </script>
 
-<slot {observer} {elementIntersections} {elementEntries} />
+<slot
+  {observer}
+  {elementIntersections}
+  {elementEntries}
+/>

package/MultipleIntersectionObserver.svelte.d.ts

@@ -53,6 +53,14 @@ export default class extends SvelteComponentTyped<
      * @default null
      */
     observer?: null | IntersectionObserver;
+
+    /**
+     * 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;
   },
   {
     /**

package/README.md

@@ -77,6 +77,27 @@ Set `once` to `true` for the intersection event to occur only once. The `element
 </IntersectionObserver>
 ```
 
+### Pausing with `skip`
+
+Set `skip` to `true` to unobserve without disconnecting the underlying observer or losing `entry`/`intersecting` state — 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 no-eval
+<script>
+  import IntersectionObserver from "svelte-intersection-observer";
+
+  let elementSkip;
+  let paused = false;
+</script>
+
+<button on:click={() => (paused = !paused)}>
+  {paused ? "Resume" : "Pause"}
+</button>
+
+<IntersectionObserver element={elementSkip} skip={paused} let:intersecting>
+  <div bind:this={elementSkip}>{intersecting ? "In view" : "Not in view"}</div>
+</IntersectionObserver>
+```
+
 ### `let:intersecting`
 
 An alternative to binding to the `intersecting` prop is to use the `let:` directive.
@@ -91,7 +112,7 @@ In the following example, the "Hello world" element will fade in when its contai
   let node;
 </script>
 
-<header />
+<header></header>
 
 <IntersectionObserver element={node} let:intersecting>
   <div bind:this={node}>
@@ -136,6 +157,65 @@ As an alternative to binding the `intersecting` prop, you can listen to the `int
 </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;
+  let sentinel;
+  let reachedEnd;
+</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>
+```
+
+### `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 `on:observe`/`on:intersect` on the observed element itself.
+
+```svelte
+<script>
+  import { intersect } from "svelte-intersection-observer";
+
+  let actionIntersecting = false;
+</script>
+
+<header class:intersecting={actionIntersecting}>
+  {actionIntersecting ? "Element is in view" : "Element is not in view"}
+</header>
+
+<div
+  use:intersect={{ once: true }}
+  on:observe={(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.
@@ -167,6 +247,56 @@ This avoids instantiating a new observer for every element.
 </MultipleIntersectionObserver>
 ```
 
+### Using with `#each`
+
+`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 items = [
+    { id: 1, text: "Item 1" },
+    { id: 2, text: "Item 2" },
+    { id: 3, text: "Item 3" },
+  ];
+
+  let refs = [];
+  let itemsContainer;
+
+  $: itemElements = refs;
+</script>
+
+<MultipleIntersectionObserver
+  elements={itemElements}
+  root={itemsContainer}
+  let: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;">
+    {#each items as item, i (item.id)}
+      <div
+        bind:this={refs[i]}
+        style="height: 100px; display: flex; align-items: center;"
+      >
+        {item.text}
+      </div>
+    {/each}
+  </div>
+</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,6 +313,9 @@ 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`       |
+
+**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.
 
 #### Dispatched events
 
@@ -213,6 +346,7 @@ 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
 
@@ -236,6 +370,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
+
+- **on:observe**: fired on the element when it is first observed or whenever an intersection change occurs
+- **on:intersect**: 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.

package/index.d.ts

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

package/index.js

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

package/intersect.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 `on:observe`/`on:intersect`.
+ */
+export const intersect: Action<
+  HTMLElement,
+  IntersectActionOptions | undefined,
+  {
+    "on:observe"?: (event: CustomEvent<IntersectionObserverEntry>) => void;
+    "on:intersect"?: (
+      event: CustomEvent<IntersectionObserverEntry & { isIntersecting: true }>,
+    ) => void;
+  }
+>;

package/intersect.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 `on:observe`/`on:intersect`.
+ * @param {HTMLElement} node
+ * @param {import("./intersect.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.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": "1.2.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",