Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lelabdev/rune-scroller

Lightweight, high-performance scroll animations for Svelte 5
https://github.com/lelabdev/rune-scroller

Last synced: 5 months ago
JSON representation

Lightweight, high-performance scroll animations for Svelte 5

Awesome Lists containing this project

README 

          
# ⚡ Rune Scroller - Full Reference



**📚 Complete API Reference** — Detailed documentation for all features and options.



---





	Rune Scroller Logo




**Lightweight scroll animations for Svelte 5** — Built with Svelte 5 Runes and IntersectionObserver API.



> 🚀 **Open Source** by [ludoloops](https://github.com/ludoloops) at [LeLab.dev](https://lelab.dev)

> 📜 Licensed under **MIT**





	

		minzipped size

	

	

		minified size

	




---



## ✨ Features



- **14KB gzipped** (47KB uncompressed) - Minimal overhead, optimized for production

- **Zero dependencies** - Pure Svelte 5 + IntersectionObserver

- **14 animations** - Fade, Zoom, Flip, Slide, Bounce variants

- **Full TypeScript support** - Type definitions generated from JSDoc

- **SSR-ready** - SvelteKit compatible

- **GPU-accelerated** - Pure CSS transforms

- **Accessible** - Respects `prefers-reduced-motion`

- **v2.0.0 New** - `onVisible` callback, ResizeObserver support, animation validation, sentinel customization

- **✨ Latest** - `useIntersection` migrated to Svelte 5 `$effect` rune for better lifecycle management

- **🚀 Bundle optimized** - CSS with custom properties, production build minification

- **🚀 v2.2.0** - Cache CSS check to eliminate 99% of reflows



---

 

## 🚀 Performance



### Cache CSS Validation (v2.2.0)



**Problem:**

- `checkAndWarnIfCSSNotLoaded()` was called for EVERY element

- Each call did:

  - `document.createElement('div')`

  - `document.body.appendChild(test)`

  - `getComputedStyle(test)` ⚠️ **Expensive!** Forces full page reflow

  - `test.remove()`

- For 100 animated elements = **100 reflows + 100 DOM operations**



**Solution:**

```javascript

// Cache to check only once per page load

let cssCheckResult = null;



export function checkAndWarnIfCSSNotLoaded() {

  if (cssCheckResult !== null) return cssCheckResult;

  // ... expensive check ...

  cssCheckResult = hasAnimation;

  return hasAnimation;

}

```



**Impact:**

- Validation runs ONLY ONCE per page load

- Eliminates layout thrashing from repeated `getComputedStyle()` calls

- For 100 elements: **99 fewer reflows** (100 → 1)

- Zero memory overhead (single boolean)



### Current Performance Metrics



| Metric | Value |

|---------|--------|

| **Bundle size** | 12.4KB (compressed), 40.3KB (unpacked) |

| **Initialization** | ~1-2ms per element |

| **Observer callback** | <0.5ms per frame |

| **CSS validation** | ~0.1ms total (v2.2.0, with cache) |

| **Memory per observer** | ~1.2KB |

| **Animation performance** | 60fps maintained |

| **Memory leaks** | 0 detected |



### Why Performance Matters



**Layout Thrashing:**

- Synchronous reflows block the main thread

- Each reflow can take 10-20ms

- For 100 elements = **1-2 seconds blocked**

- User sees stuttering/jank while scrolling



**Solution:**

- Cache = 1 reflow instead of N

- 99% improvement on pages with many animations

- Smoother scrolling, better UX



### Optimized Code Patterns



**IntersectionObserver:**

- Native API (no scroll listeners)

- Fast callback (<0.5ms per frame)

- No debounce needed (browser handles this efficiently)



**CSS Animations:**

- Transforms only (GPU-accelerated)

- No layout/repaint during animation

- `will-change` on visible elements only



**DOM Operations:**

- `insertAdjacentElement('beforebegin')` instead of `insertBefore`

- `offsetHeight` instead of `getBoundingClientRect()` (avoids transform issues)

- Complete cleanup on destroy



**Memory Management:**

- All observers disconnected

- Sentinel and wrapper removed

- State prevents double-disconnects

- 0 memory leaks detected (121/121 tests)



### Future Considerations



**1. `will-change` Timing**

- Currently: `.is-visible { will-change: transform, opacity; }`

- Trade-off: Stays active after animation (consumes GPU memory)

- Consideration: Use `transitionend` event to remove `will-change`

- Recommendation: Keep current (GPU memory is cheap)



**2. Threshold Tuning**

- Current: `threshold: 0` (triggers as soon as 1px is visible)

- Alternative: `threshold: 0.1` or `threshold: 0.25`

- Trade-off: Higher threshold = later trigger = smoother stagger

- Recommendation: Keep `threshold: 0` for immediate feedback



**3. requestIdleCallback**

- Potential: Defer non-critical setup to browser idle time

- Trade-off: Complex to implement, marginal benefit

- Recommendation: Not needed (current performance is excellent)



**4. Testing on Low-End Devices**

- Test on mobile phones, older browsers

- Use DevTools CPU throttling

- Consider Lighthouse/Puppeteer for automated testing

- Ensure 60fps maintained on real devices



### What NOT to Optimize



**Anti-patterns to avoid:**



1. ❌ **Premature optimization**

   - Don't optimize without measurements

   - Profile first, optimize later

   - "Premature optimization is the root of all evil"



2. ❌ **Over-engineering**

   - Complex solutions for small gains

   - Keep it simple when possible

   - Don't sacrifice readability for micro-optimizations



3. ❌ **Breaking performance for size**

   - Bundle size matters (12.4KB is excellent)

   - Don't add huge dependencies for minor improvements



4. ❌ **Optimizing unused paths**

   - Focus on hot paths (element creation, scroll, intersection)

   - Cold paths (initialization, destroy) less critical



5. ❌ **Sacrificing maintainability**

   - Don't sacrifice code clarity for micro-optimizations

   - Comments should explain WHY, not just WHAT

   - Keep code simple and understandable



### Performance Testing



**Recommended approach:**

1. Create a benchmark with 100-1000 animated elements

2. Measure: initialization, first animation, scroll performance, cleanup

3. Profile with DevTools Performance tab

4. Test on real pages (not just benchmarks)

5. Verify 60fps is maintained during scroll



**Tools:**

- Chrome DevTools Performance tab

- Firefox Performance Profiler

- Web Inspector (Safari)

- Lighthouse (PageSpeed, accessibility, best practices)



---

 

## 📦 Installation



```bash

npm install rune-scroller

# or

pnpm add rune-scroller

# or

yarn add rune-scroller

```



---



## 🚀 Quick Start



```svelte



	import runeScroller from 'rune-scroller';





	
Animated Heading







	
Smooth fade and slide







	Bounces on every scroll



```



That's it! The CSS animations are included automatically when you import rune-scroller.



### Option 2: Manual CSS Import



For fine-grained control, import CSS manually:



**Step 1: Import CSS in your root layout (recommended for SvelteKit):**



```svelte



	import 'rune-scroller/animations.css';

	let { children } = $props();



{@render children()}

```



**Or import in each component:**



```svelte



	import runeScroller from 'rune-scroller';

	import 'rune-scroller/animations.css';



```



**Step 2: Use the animations**



```svelte



	import runeScroller from 'rune-scroller';

	// CSS already imported in layout or above





	Animated content



```



---



## 🎨 Available Animations



### Fade (5)

- `fade-in` - Simple opacity fade

- `fade-in-up` - Fade + move up 300px

- `fade-in-down` - Fade + move down 300px

- `fade-in-left` - Fade + move from right 300px

- `fade-in-right` - Fade + move from left 300px



### Zoom (5)

- `zoom-in` - Scale from 0.3 to 1

- `zoom-out` - Scale from 2 to 1

- `zoom-in-up` - Zoom (0.5→1) + move up 300px

- `zoom-in-left` - Zoom (0.5→1) + move from right 300px

- `zoom-in-right` - Zoom (0.5→1) + move from left 300px



### Others (4)

- `flip` - 3D flip on Y-axis

- `flip-x` - 3D flip on X-axis

- `slide-rotate` - Slide + rotate 10°

- `bounce-in` - Bouncy entrance (spring effect)



---



## ⚙️ Options



```typescript

interface RuneScrollerOptions {

	animation?: AnimationType;  // Animation name (default: 'fade-in')

	duration?: number;          // Duration in ms (default: 800)

	repeat?: boolean;           // Repeat on scroll (default: false)

	debug?: boolean;            // Show sentinel as visible line (default: false)

	offset?: number;            // Sentinel offset in px (default: 0, negative = above)

	onVisible?: (element: HTMLElement) => void;  // Callback when animation triggers (v2.0.0+)

	sentinelColor?: string;     // Sentinel debug color, e.g. '#ff6b6b' (v2.0.0+)

	sentinelId?: string;        // Custom ID for sentinel identification (v2.0.0+)

}

```



### Option Details



- **`animation`** - Type of animation to play. Choose from 14 built-in animations listed above. Invalid animations automatically fallback to 'fade-in' with a console warning.

- **`duration`** - How long the animation lasts in milliseconds (default: 800ms).

- **`repeat`** - If `true`, animation plays every time sentinel enters viewport. If `false`, plays only once.

- **`debug`** - If `true`, displays the sentinel element as a visible line below your element. Useful for seeing exactly when animations trigger. Default color is cyan (#00e0ff), customize with `sentinelColor`.

- **`offset`** - Offset of the sentinel in pixels. Positive values move sentinel down (delays animation), negative values move it up (triggers earlier). Useful for large elements where you want animation to trigger before the entire element is visible.

- **`onVisible`** *(v2.0.0+)* - Callback function triggered when the animation becomes visible. Receives the animated element as parameter. Useful for analytics, lazy loading, or triggering custom effects.

- **`sentinelColor`** *(v2.0.0+)* - Customize the debug sentinel color (e.g., '#ff6b6b' for red). Only visible when `debug: true`. Useful for distinguishing multiple sentinels on the same page.

- **`sentinelId`** *(v2.0.0+)* - Set a custom ID for the sentinel element. If not provided, an auto-ID is generated (`sentinel-1`, `sentinel-2`, etc.). Useful for identifying sentinels in DevTools and tracking which element owns which sentinel.



### Examples



```svelte





	Content






	Fast animation






	Repeats every time you scroll






	The cyan line below this shows when animation will trigger






	Full featured example






	Large content that needs early triggering






	Content with delayed animation




 {

		console.log('Animation visible!', el);

		// Track analytics, load images, trigger API calls, etc.

		window.gtag?.('event', 'animation_visible', { element: el.id });

	}

}}>

	Tracked animation






	Red debug sentinel






	Identified sentinel (shows "hero-zoom" in debug mode)






	Auto-identified sentinel



```



---



## 🎯 How It Works



Rune Scroller uses **sentinel-based triggering**:



1. An invisible 1px sentinel element is created below your element

2. When the sentinel enters the viewport, animation triggers

3. This ensures precise timing regardless of element size

4. Uses native IntersectionObserver for performance

5. Pure CSS animations (GPU-accelerated)

6. *(v2.0.0)* Sentinel automatically repositions on element resize via ResizeObserver



**Why sentinels?**

- Accurate timing across all screen sizes

- No complex offset calculations

- Handles staggered animations naturally

- Sentinel stays fixed while element animates (no observer confusion with transforms)



**Automatic ResizeObserver** *(v2.0.0+)*

- Sentinel repositions automatically when element resizes

- Works with responsive layouts and dynamic content

- No configuration needed—it just works



---



## 🌐 SSR Compatibility



Works seamlessly with SvelteKit. Simply import rune-scroller in your root layout:



```svelte



	import runeScroller from 'rune-scroller';

	let { children } = $props();



{@render children()}

```



Then use animations anywhere in your app:



```svelte



	import runeScroller from 'rune-scroller';





	Works in SvelteKit SSR!



```



The library checks for browser environment and gracefully handles server-side rendering.



---



## ♿ Accessibility



Respects `prefers-reduced-motion`:



```css

/* In animations.css */

@media (prefers-reduced-motion: reduce) {

	.scroll-animate {

		animation: none !important;

		opacity: 1 !important;

		transform: none !important;

	}

}

```



Users who prefer reduced motion will see content without animations.



---



## 📚 API Reference

### Public API



Rune Scroller exports a **single action-based API** (no components):



1. **`runeScroller`** (default) - Sentinel-based, simple, powerful



**Why actions instead of components?**

- Actions are lightweight directives

- No DOM wrapper overhead

- Better performance

- More flexible



### Main Export



```typescript

// CSS is automatically included

import runeScroller from 'rune-scroller';



// Named exports

import {

	useIntersection,            // Composable

	useIntersectionOnce,        // Composable

	calculateRootMargin         // Utility

} from 'rune-scroller';



// Types

import type {

	AnimationType,

	RuneScrollerOptions,

	IntersectionOptions,

	UseIntersectionReturn

} from 'rune-scroller';

```



### TypeScript Types



```typescript

type AnimationType =

	| 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right'

	| 'zoom-in' | 'zoom-out' | 'zoom-in-up' | 'zoom-in-left' | 'zoom-in-right'

	| 'flip' | 'flip-x' | 'slide-rotate' | 'bounce-in';



interface RuneScrollerOptions {

	animation?: AnimationType;

	duration?: number;

	repeat?: boolean;

	debug?: boolean;

	offset?: number;

	onVisible?: (element: HTMLElement) => void;      // v2.0.0+

	sentinelColor?: string;                          // v2.0.0+

	sentinelId?: string;                             // v2.0.0+

}

```



---



## 📖 Examples



### Staggered Animations



```svelte



	import runeScroller from 'rune-scroller';



	const items = [

		{ title: 'Feature 1', description: 'Description 1' },

		{ title: 'Feature 2', description: 'Description 2' },

		{ title: 'Feature 3', description: 'Description 3' }

	];





	{#each items as item}

		


			
{item.title}


			
{item.description}


		


	{/each}



```



### Hero Section



```svelte



	
Welcome







	
Engaging content







	Get Started



```



---



## 🔗 Links



- **npm Package**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)

- **GitHub**: [lelabdev/rune-scroller](https://github.com/lelabdev/rune-scroller)

- **Changelog**: [CHANGELOG.md](https://github.com/lelabdev/rune-scroller/blob/main/lib/CHANGELOG.md)



---



## 📄 License



MIT © [ludoloops](https://github.com/ludoloops)



---



## 🤝 Contributing



Contributions welcome! Please open an issue or PR on GitHub.



```bash

# Development

bun install

bun run dev

bun test

bun run build

```



---



Made with ❤️ by [LeLab.dev](https://lelab.dev)