Skip to content

perf(scroll-state): remove AnimationFrames loop #410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fvarano wants to merge 2 commits into
base: main
Choose a base branch
from
Open

perf(scroll-state): remove AnimationFrames loop #410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16c29e0
perf(scroll-state): remove AnimationFrames loop, add optional Mutatio…
fvarano Feb 27, 2026
9be7924
docs(scroll-state): add observe option
fvarano Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions packages/runed/src/lib/utilities/scroll-state/scroll-state.svelte.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import type { MaybeGetter } from "$lib/internal/types.js";
import { AnimationFrames } from "$lib/utilities/animation-frames/index.js";
import { useMutationObserver } from "$lib/utilities/use-mutation-observer/index.js";
import { useDebounce } from "$lib/utilities/use-debounce/index.js";
import { useEventListener } from "$lib/utilities/use-event-listener/index.js";
import { onMount } from "svelte";
Expand Down Expand Up @@ -34,6 +34,16 @@ export interface ScrollStateOptions {
| undefined
>;

/**
* Use MutationObserver to monitor DOM changes that might affect scroll state,
* such as attribute modifications, child node additions/removals, or subtree changes.
*
* Useful when content changes dynamically without triggering scroll events.
*
* @default false
*/
observe?: MaybeGetter<boolean | undefined>;

/**
* Called during scroll events.
*/
Expand Down Expand Up @@ -86,6 +96,7 @@ export class ScrollState {
#options!: ScrollStateOptions;
element = $derived(extract(this.#options.element));
idle = $derived.by(() => extract(this.#options?.idle, 200));
observe = $derived(extract(this.#options.observe, false));
offset = $derived(
extract(this.#options.offset, {
left: 0,
Expand Down Expand Up @@ -171,8 +182,24 @@ export class ScrollState {
this.setArrivedState();
});

// overkill?
new AnimationFrames(() => this.setArrivedState());
if (
this.observe &&
this.element &&
this.element !== window &&
this.element !== window.document
) {
useMutationObserver(
() => this.element as HTMLElement | null,
() => {
this.setArrivedState();
},
{
attributes: true,
childList: true,
subtree: true,
}
);
}
}

/**
Expand Down
21 changes: 11 additions & 10 deletions sites/docs/src/content/utilities/scroll-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,16 +63,17 @@ You can now access:

You can configure `ScrollState` via the following options:

| Option | Type | Description |
| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
| `element` | `MaybeGetter<HTMLElement \| Window \| Document \| null>` | The scroll container (required). |
| `idle` | `MaybeGetter<number \| undefined>` | Debounce time (ms) after scroll ends. Default: `200`. |
| `offset` | `{ top?, bottom?, left?, right? }` | Pixel thresholds for "arrived" state detection. Default: `0` for all. |
| `onScroll` | `(e: Event) => void` | Callback for scroll events. |
| `onStop` | `(e: Event) => void` | Callback after scrolling stops. |
| `eventListenerOptions` | `AddEventListenerOptions` | Scroll listener options. Default: `{ passive: true, capture: false }`. |
| `behavior` | `ScrollBehavior` | Scroll behavior: `"auto"`, `"smooth"`, etc. Default: `"auto"`. |
| `onError` | `(error: unknown) => void` | Optional error handler. Default: `console.error`. |
| Option | Type | Description |
| ---------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `element` | `MaybeGetter<HTMLElement \| Window \| Document \| null>` | The scroll container (required). |
| `idle` | `MaybeGetter<number \| undefined>` | Debounce time (ms) after scroll ends. Default: `200`. |
| `offset` | `{ top?, bottom?, left?, right? }` | Pixel thresholds for "arrived" state detection. Default: `0` for all. |
| `observe` | `MaybeGetter<boolean \| undefined>` | Enable MutationObserver to detect DOM changes affecting scroll state. Default: `false`. |
| `onScroll` | `(e: Event) => void` | Callback for scroll events. |
| `onStop` | `(e: Event) => void` | Callback after scrolling stops. |
| `eventListenerOptions` | `AddEventListenerOptions` | Scroll listener options. Default: `{ passive: true, capture: false }`. |
| `behavior` | `ScrollBehavior` | Scroll behavior: `"auto"`, `"smooth"`, etc. Default: `"auto"`. |
| `onError` | `(error: unknown) => void` | Optional error handler. Default: `console.error`. |

## Notes

Expand Down