svelte-intersection-observer 0.10.2 → 1.1.0

package/README.md

@@ -12,22 +12,19 @@ Try it in the [Svelte REPL](https://svelte.dev/repl/8cd2327a580c4f429c71f7df999b
 
 ## Installation
 
-**Yarn**
+```sh
+# NPM
+npm i svelte-intersection-observer
 
-```bash
-yarn add -D svelte-intersection-observer
-```
-
-**NPM**
+# pnpm
+pnpm i svelte-intersection-observer
 
-```bash
-npm i -D svelte-intersection-observer
-```
+# Bun
+bun i svelte-intersection-observer
 
-**pnpm**
+# Yarn
+yarn add svelte-intersection-observer
 
-```bash
-pnpm i -D svelte-intersection-observer
 ```
 
 ## Usage
@@ -139,29 +136,109 @@ As an alternative to binding the `intersecting` prop, you can listen to the `int
 </IntersectionObserver>
 ```
 
+### Multiple elements
+
+For performance, use `MultipleIntersectionObserver` to observe multiple elements.
+
+This avoids instantiating a new observer for every element.
+
+```svelte
+<script>
+  import { MultipleIntersectionObserver } from "svelte-intersection-observer";
+
+  let ref1;
+  let ref2;
+
+  $: elements = [ref1, ref2];
+</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) ? "✓" : "✗"}
+    </div>
+  </header>
+
+  <div bind:this={ref1}>Item 1</div>
+  <div bind:this={ref2}>Item 2</div>
+</MultipleIntersectionObserver>
+```
+
 ## API
 
-### Props
+### IntersectionObserver
+
+#### Props
 
-| Name         | Description                                                 | Type                                                                                                      | Default value |
-| :----------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------ |
-| element      | Observed element                                            | `HTMLElement`                                                                                             | `null`        |
-| once         | Unobserve the element after the first intersection event    | `boolean`                                                                                                 | `false`       |
-| intersecting | `true` if the observed element is intersecting the viewport | `boolean`                                                                                                 | `false`       |
-| root         | Containing element                                          | `null` or `HTMLElement`                                                                                   | `null`        |
-| rootMargin   | Margin offset of the containing element                     | `string`                                                                                                  | `"0px"`       |
-| threshold    | Percentage of element visibile to trigger an event          | `number` between 0 and 1, or an array of `number`s between 0 and 1                                        | `0`           |
-| entry        | Observed element metadata                                   | [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) | `null`        |
-| observer     | `IntersectionObserver` instance                             | [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)           | `null`        |
+| Name         | Description                                                 | Type                                                                                                                | Default value |
+| :----------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------ |
+| element      | Observed element                                            | `null` or `HTMLElement`                                                                                             | `null`        |
+| once         | Unobserve the element after the first intersection event    | `boolean`                                                                                                           | `false`       |
+| intersecting | `true` if the observed element is intersecting the viewport | `boolean`                                                                                                           | `false`       |
+| 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`           |
+| 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`        |
 
-### Dispatched events
+#### Dispatched events
 
 - **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
 
 The `e.detail` dispatched by the `observe` and `intersect` events is an [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) interface.
 
-Note that all properties in `IntersectionObserverEntry` are read-only.
+#### Slot props
+
+| Name         | Type                                                                                                                |
+| :----------- | :------------------------------------------------------------------------------------------------------------------ |
+| intersecting | `boolean`                                                                                                           |
+| entry        | `null` or [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) |
+| observer     | [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)                     |
+
+### MultipleIntersectionObserver
+
+#### Props
+
+| Name                 | Description                                           | Type                                                                                                                                    | Default value |
+| :------------------- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
+| elements             | Array of HTML elements to observe                     | `Array<HTMLElement \| null>`                                                                                                            | `[]`          |
+| once                 | Unobserve elements after the first intersection event | `boolean`                                                                                                                               | `false`       |
+| 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`           |
+| 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`        |
+
+#### Dispatched events
+
+- **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
+
+The `e.detail` for both events includes:
+
+```ts
+{
+  entry: IntersectionObserverEntry;
+  target: HTMLElement;
+}
+```
+
+#### Slot props
+
+| Name                 | Type                                                                                                                                    |
+| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| observer             | [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)                                         |
+| elementIntersections | `Map<HTMLElement \| null, boolean>`                                                                                                     |
+| elementEntries       | `Map<HTMLElement \| null,` [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)`>` |
+
+### `IntersectionObserverEntry` interface
+
+Note that all properties in [IntersectionObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) are read-only.
 
 <details>
  <summary><code>IntersectionObserverEntry</code></summary>
@@ -208,21 +285,6 @@ interface IntersectionObserverEntry {
 
 </details>
 
-## Examples
-
-The [examples folder](examples/) contains sample set-ups.
-
-- [examples/sveltekit](examples/sveltekit)
-- [examples/vite](examples/vite)
-- [examples/rollup](examples/rollup)
-- [examples/webpack](examples/webpack)
-
-## TypeScript support
-
-Svelte version 3.31 or greater is required to use this module with TypeScript.
-
-TypeScript definitions for this component are located in the [types folder](types/).
-
 ## Changelog
 
 [Changelog](CHANGELOG.md)

package/package.json

@@ -1,59 +1,39 @@
 {
   "name": "svelte-intersection-observer",
-  "version": "0.10.2",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "Detect if an element is in the viewport using the Intersection Observer API",
   "author": "Eric Liu (https://github.com/metonym)",
+  "type": "module",
   "svelte": "./src/index.js",
-  "main": "./lib/index.js",
-  "module": "./lib/index.mjs",
-  "types": "./types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "svelte": "./src/index.js"
-    },
-    "./src/*.svelte": {
-      "types": "./types/*.svelte.d.ts",
-      "import": "./src/*.svelte"
-    },
-    "./src/*": {
-      "types": "./types/*.d.ts",
-      "import": "./src/*.js"
-    }
-  },
-  "scripts": {
-    "dev": "rollup -cw",
-    "build": "rollup -c",
-    "prepack": "BUNDLE=true rollup -c",
-    "test:types": "svelte-check --workspace test",
-    "test:examples": "node test/examples",
-    "format": "prettier --ignore-path .gitignore --write '.'"
-  },
-  "devDependencies": {
-    "prettier": "^3.0.0",
-    "prettier-plugin-svelte": "^3.0.0",
-    "svelte": "^4.1.0",
-    "svelte-check": "^3.4.6",
-    "svelte-readme": "^3.6.3"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/metonym/svelte-intersection-observer.git"
+    "url": "git+https://github.com/metonym/svelte-intersection-observer.git"
   },
   "homepage": "https://github.com/metonym/svelte-intersection-observer",
   "bugs": "https://github.com/metonym/svelte-intersection-observer/issues",
   "keywords": [
+    "svelte",
+    "svelte component",
     "intersection observer",
     "viewport",
     "lazy-loading",
-    "conditional",
-    "svelte",
-    "svelte component"
+    "conditional"
   ],
-  "files": [
-    "lib",
-    "src",
-    "types"
-  ]
-}
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "svelte": "./index.js"
+    },
+    "./*.svelte": {
+      "types": "./*.svelte.d.ts",
+      "import": "./*.svelte"
+    },
+    "./*": {
+      "types": "./*.d.ts",
+      "import": "./*.js"
+    }
+  }
+}

package/src/IntersectionObserver.svelte

@@ -1,7 +1,7 @@
 <script>
   /**
    * The HTML Element to observe.
-   * @type {HTMLElement}
+   * @type {null | HTMLElement}
    */
   export let element = null;
 
@@ -21,7 +21,7 @@
   /**
    * Specify the containing element.
    * Defaults to the browser viewport.
-   * @type {HTMLElement}
+   * @type {null | HTMLElement}
    */
   export let root = null;
 
@@ -50,7 +50,10 @@
 
   const dispatch = createEventDispatcher();
 
+  /** @type {null | string} */
   let prevRootMargin = null;
+
+  /** @type {null | HTMLElement} */
   let prevElement = null;
 
   const initialize = () => {
@@ -61,7 +64,7 @@
           intersecting = _entry.isIntersecting;
         });
       },
-      { root, rootMargin, threshold }
+      { root, rootMargin, threshold },
     );
   };
 
@@ -83,21 +86,21 @@
       if (entry.isIntersecting) {
         dispatch("intersect", entry);
 
-        if (once) observer.unobserve(element);
+        if (element && once) observer?.unobserve(element);
       }
     }
 
     await tick();
 
     if (element !== null && element !== prevElement) {
-      observer.observe(element);
+      observer?.observe(element);
 
-      if (prevElement !== null) observer.unobserve(prevElement);
+      if (prevElement !== null) observer?.unobserve(prevElement);
       prevElement = element;
     }
 
     if (prevRootMargin && rootMargin !== prevRootMargin) {
-      observer.disconnect();
+      observer?.disconnect();
       prevElement = null;
       initialize();
     }

package/src/IntersectionObserver.svelte.d.ts

@@ -0,0 +1,79 @@
+import type { SvelteComponentTyped } from "svelte";
+
+export default class extends SvelteComponentTyped<
+  {
+    /**
+     * 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;
+
+    /**
+     * `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;
+
+    /**
+     * 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[];
+
+    /**
+     * 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>;
+
+    /**
+     * 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;
+    };
+  }
+> {}

package/src/MultipleIntersectionObserver.svelte

@@ -0,0 +1,137 @@
+<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";
+
+  /**
+   * Percentage of element visibility to trigger an event.
+   * Value must be between 0 and 1.
+   */
+  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();
+
+  /** @type {null | string} */
+  let prevRootMargin = null;
+
+  /** @type {null | HTMLElement} */
+  let prevElement = null;
+
+  /** @type {(HTMLElement | null)[]} */
+  let prevElements = [];
+
+  const initialize = () => {
+    observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((_entry) => {
+          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);
+          }
+        });
+      },
+      { root, rootMargin, threshold },
+    );
+  };
+
+  onMount(() => {
+    initialize();
+
+    return () => {
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+    };
+  });
+
+  afterUpdate(async () => {
+    await tick();
+
+    if (elements.length > 0) {
+      const newElements = elements.filter(
+        (el) => el && !prevElements.includes(el),
+      );
+      newElements.forEach((el) => {
+        if (el) observer?.observe(el);
+      });
+
+      const removedElements = prevElements.filter(
+        (el) => el && !elements.includes(el),
+      );
+      removedElements.forEach((el) => {
+        if (el) observer?.unobserve(el);
+      });
+
+      prevElements = [...elements];
+    }
+
+    if (prevRootMargin && rootMargin !== prevRootMargin) {
+      observer?.disconnect();
+      prevElement = null;
+      prevElements = [];
+      initialize();
+
+      elements
+        .filter((el) => el)
+        .forEach((el) => {
+          if (el) observer?.observe(el);
+        });
+    }
+
+    prevRootMargin = rootMargin;
+  });
+</script>
+
+<slot {observer} {elementIntersections} {elementEntries} />

package/src/MultipleIntersectionObserver.svelte.d.ts

@@ -0,0 +1,82 @@
+import type { SvelteComponentTyped } 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)[];
+
+    /**
+     * 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;
+
+    /**
+     * 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[];
+
+    /**
+     * 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>;
+
+    /**
+     * `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;
+    }>;
+
+    /**
+     * 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>;
+    };
+  }
+> {}

package/src/index.d.ts

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

package/src/index.js

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