svelte-attach-motion

Motion animations for Svelte 5, as attachments.

Docs & demo: ds2l9pktw39ce.cloudfront.net

No wrapper components and no <motion.div>. Add animation to the elements you already have, with automatic cleanup and prefers-reduced-motion support built in.

<script>
	import { animate, inView, hover, press } from 'svelte-attach-motion';
</script>

<h1 {@attach animate({ opacity: [0, 1], y: [16, 0] })}>Hello</h1>

<section {@attach inView({ opacity: 1 }, { initial: { opacity: 0 } })}>…</section>

<button {@attach press({ scale: 0.95 })} {@attach hover({ y: -2 })}>Save</button>

Install

npm install svelte-attach-motion motion

Requires Svelte 5.29+ (attachments) and Motion 13. Motion is a peer dependency, so your app controls its version.

API

| Attachment | What it does | | ------------------------------------ | ------------------------------------------------------------------------------- | | animate(keyframes, options?) | Animates on mount, and again whenever reactive values in keyframes change. | | inView(keyframes, options?) | Animates when the element enters the viewport. once: false replays each time. | | scrollAnimate(keyframes, options?) | Links an animation to the element's scroll position. | | scrollProgress(callback, options?) | Calls callback(progress) with 0–1 as the element (or page) scrolls. | | hover(keyframes, options?) | Animates while a mouse hovers the element, then returns to rest. Ignores touch. | | press(keyframes, options?) | Animates while pressed, by pointer or keyboard (Enter), then returns to rest. |

All animating attachments accept:

• transition: Motion transition options (duration, delay, ease, type: 'spring', ...).
• reducedMotion: 'user' (default), 'always' or 'never'. See below.

hover and press also accept rest, the values to return to when the gesture ends. You rarely need it: transform shorthands return to their identity (scale: 1, x: 0, ...) and other properties return to their computed style at mount time.

Reactive animations

Attachments re-run when the state they read changes, so this animates the knob every time on flips:

<script>
	let on = $state(false);
</script>

<button onclick={() => (on = !on)}>
	<span {@attach animate({ x: on ? 40 : 0 }, { transition: { type: 'spring' } })}></span>
</button>

Reduced motion

By default every attachment respects the user's prefers-reduced-motion setting:

• animate, inView, hover and press still reach their final state, so content is never left hidden, but instantly.
• scrollAnimate is skipped entirely, because scroll-linked motion is a common trigger for discomfort.
• scrollProgress only reports numbers, so it is left to your callback.

Use reducedMotion: 'never' only for motion that is essential to understanding the UI.

No flash on server-rendered pages

Attachments run once JavaScript has loaded. On a server-rendered or prerendered page, an entrance animation would otherwise show the element, hide it when the attachment mounts, then animate it in.

Import the stylesheet once and add data-reveal to entrance animations:

<!-- +layout.svelte -->
<script>
	import 'svelte-attach-motion/reveal.css';
</script>

<h1 data-reveal {@attach animate({ opacity: [0, 1], y: [12, 0] })}>…</h1>

<section data-reveal {@attach inView({ opacity: 1, y: 0 }, { initial: { opacity: 0, y: 24 } })}>
	…
</section>

• Elements are hidden from the first paint only when the browser can run scripts (@media (scripting: enabled)), so content stays visible without JavaScript.
• animate and inView take over when they mount and remove the attribute after their first frame. On inView, initial defaults to { opacity: 0 } for data-reveal elements.
• If the JavaScript never loads, a CSS fail-safe shows the element after 3 seconds.
• Only use it on entrance animations that end at opacity: 1.

Name clashes with Motion

If you also import from motion directly, alias one side:

import { animate as motionAnimate } from 'motion';
import { animate } from 'svelte-attach-motion';

Why attachments?

Svelte 5 attachments are functions that run when an element mounts and clean up when it unmounts, and they re-run when their reactive inputs change. That maps directly onto Motion's vanilla API, which returns a cleanup function for everything. The result is a thin layer: there are no components to learn and nothing changes about your markup.

Development

pnpm install
pnpm dev          # docs + demo site at localhost:5173
pnpm check        # svelte-check (TypeScript)
pnpm lint         # Prettier + ESLint
pnpm test:unit    # Vitest
pnpm test:e2e     # Playwright (run `pnpm exec playwright install chromium` once first)
pnpm build        # static site to build/ and the package to dist/

Project layout:

src/lib/                    the published package
  attachments/              animate, inView, scroll*, hover/press
  internal/                 pure helpers with unit tests
src/routes/                 docs site and the "Spot the phish" demo
e2e/                        Playwright tests (animations, gestures, reduced motion, demo)