svelte-intersection-observer 2.0.0 → 2.1.0

package/IntersectionObserver.svelte

@@ -48,7 +48,11 @@
           onobserve?.(_entry);
 
           if (_entry.isIntersecting) {
-            onintersect?.(_entry);
+            onintersect?.(
+              /** @type {IntersectionObserverEntry & { isIntersecting: true }} */ (
+                _entry
+              ),
+            );
 
             if (element && once) observer?.unobserve(element);
           }

package/MultipleIntersectionObserver.svelte

@@ -50,7 +50,13 @@
           onobserve?.({ entry: _entry, target });
 
           if (_entry.isIntersecting) {
-            onintersect?.({ entry: _entry, target });
+            onintersect?.({
+              entry:
+                /** @type {IntersectionObserverEntry & { isIntersecting: true }} */ (
+                  _entry
+                ),
+              target,
+            });
             if (once) observer?.unobserve(target);
           }
         }

package/README.md

@@ -1,12 +1,19 @@
 # svelte-intersection-observer
 
+<!-- HIDE_START -->
 [![NPM][npm]][npm-url]
+<!-- HIDE_END -->
 
 > 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).
 
 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:`.
+This zero-dependency library offers several ways to observe elements:
+
+- `IntersectionObserver`: component for observing a single element
+- `MultipleIntersectionObserver`: component for observing multiple elements (shared observer for better performance)
+- `intersect`: action for observing an element directly with `use:`
+- `intersectAttachment`: attachment for observing an element directly with `{@attach}` (Svelte 5.29+)
 
 Try it in the [Svelte REPL](https://svelte.dev/repl/8cd2327a580c4f429c71f7df999bd51d).
 
@@ -263,6 +270,37 @@ As an alternative to the `IntersectionObserver` component, use the `intersect` a
 
 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.
 
+### `intersectAttachment` attachment
+
+As of Svelte 5.29, [attachments](https://svelte.dev/docs/svelte/svelte-attachments) are the preferred replacement for actions. `intersectAttachment` wraps the `intersect` action with `svelte/attachments`'s `fromAction`, reusing the same observer logic but plugging into `{@attach ...}` instead of `use:`.
+
+Attachments have a few architectural advantages over actions:
+
+- No separate `update()` lifecycle method; they rerun reactively like a `$effect`
+- Just plain functions, so they're easier to compose and generate dynamically
+- Can be forwarded through components as ordinary props, unlike actions
+
+```svelte
+<script>
+  import { intersectAttachment } from "svelte-intersection-observer";
+
+  let attachmentIntersecting = $state(false);
+</script>
+
+<header class:intersecting={attachmentIntersecting}>
+  {attachmentIntersecting ? "Element is in view" : "Element is not in view"}
+</header>
+
+<div
+  {@attach intersectAttachment(() => ({ once: true }))}
+  onobserve={(e) => (attachmentIntersecting = e.detail.isIntersecting)}
+>
+  Hello world
+</div>
+```
+
+**Note**: unlike `use:intersect`, which takes the options object directly, `intersectAttachment` takes a function that _returns_ the options object (this is how `fromAction` tracks reactive dependencies). `intersect` remains fully supported; use whichever fits your codebase.
+
 ### Multiple elements
 
 For performance, use `MultipleIntersectionObserver` to observe multiple elements with a single shared observer instead of instantiating a new one for every element.
@@ -417,7 +455,9 @@ Both callbacks are called with:
 | elementIntersections | `Map<HTMLElement \| null, boolean>`                                                                                                     |
 | elementEntries       | `Map<HTMLElement \| null,` [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)`>` |
 
-### `intersect` action
+### `intersect` action / `intersectAttachment` attachment
+
+`intersectAttachment` is a thin wrapper around the `intersect` action (see [above](#intersectattachment-attachment)), so both share the same options and dispatched events.
 
 #### Options
 

package/index.d.ts

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

package/index.js

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

package/intersect.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { Action } from "svelte/action";
+import type { Attachment } from "svelte/attachments";
 
 export interface IntersectActionOptions {
   /**
@@ -51,3 +52,20 @@ export const intersect: Action<
     ) => void;
   }
 >;
+
+/**
+ * Svelte attachment that observes the element with the Intersection Observer
+ * API. Equivalent to `intersect`, for use with `{@attach}` instead of `use:`.
+ */
+export function intersectAttachment(
+  getOptions?: () => IntersectActionOptions,
+): Attachment<HTMLElement>;
+
+declare module "svelte/elements" {
+  export interface HTMLAttributes<T> {
+    onobserve?: (event: CustomEvent<IntersectionObserverEntry>) => void;
+    onintersect?: (
+      event: CustomEvent<IntersectionObserverEntry & { isIntersecting: true }>,
+    ) => void;
+  }
+}

package/intersect.svelte.js

@@ -1,3 +1,5 @@
+import { fromAction } from "svelte/attachments";
+
 /**
  * Svelte action that observes `node` with the Intersection Observer API.
  * Dispatches `observe` (on every change) and `intersect` (on entering the
@@ -67,3 +69,13 @@ export function intersect(node, options = {}) {
     },
   };
 }
+
+/**
+ * Svelte attachment that observes the element with the Intersection Observer
+ * API. Equivalent to the `intersect` action, for use with `{@attach}` instead
+ * of `use:`. Wraps `intersect` via `svelte/attachments`'s `fromAction`.
+ * @param {() => import("./intersect.svelte.d.ts").IntersectActionOptions} [getOptions]
+ */
+export function intersectAttachment(getOptions = () => ({})) {
+  return fromAction(intersect, getOptions);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-intersection-observer",
-  "version": "2.0.0",
+  "version": "2.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)",