gsap-sveltekit git:20260908.0f6ec59A

Immutable. This exact content is served forever at /api/v1/blob/2d5e301f0fbdac4d.

---
name: gsap-sveltekit
description: "Build or review SvelteKit animation on Svelte 5: GSAP page transitions, component enter/exit, scroll effects, route reuse, and cleanup. Use for interrupted navigation or choosing GSAP, Svelte transitions, or View Transitions, even when GSAP is unnamed. Not for plain Svelte or isolated GSAP API questions."
license: MIT
metadata:
  short-description: GSAP page and component lifecycles in SvelteKit
---

# GSAP SvelteKit

**mount → initial state → intro → settled → outro → end state → unmount**

Mount and unmount belong to Svelte; animation owns the five phases between them. SvelteKit reuses pages on parameter changes and preserves shared layouts, so a new page lifecycle need not mean a new node.

Keep the requested look and existing project conventions. Add GSAP/plugins only as needed; do not replace the chosen animation library unless asked.

## Start with the project

Read repository instructions, existing animation, layouts, navigation, CSS, accessibility conventions, and checks. Then:

1. Confirm SvelteKit with Svelte 5 in runes mode. Plain Svelte without SvelteKit routing belongs to `gsap-frameworks`. For Svelte 4 or legacy mode, say so and map `$effect` advice onto `onMount` and `onDestroy`.
2. Read the installed `@sveltejs/kit` and `svelte` versions. Prefer their bundled types over memory: `node_modules/@sveltejs/kit/types/index.d.ts` documents every navigation object, and `node_modules/svelte/types/index.d.ts` the runes and lifecycle exports. Version gates: `onNavigate` (1.24), `$app/state` (2.12; use `$app/stores` before), `to.scroll` on navigation targets (2.51), `prefersReducedMotion` in `svelte/motion` (5.7), `{@attach}` (5.29).
3. Check `svelte.config.js`, page options (`ssr`, `csr`, `prerender`), `data-sveltekit-preload-data` on `body` in `src/app.html`, and links marked `data-sveltekit-reload`. A page with `csr = false` has no client router and no navigation hooks; a reload link is a full document load. Treat both as plain documents.

## Choose the engine

Use Svelte `transition:` / `in:` / `out:` for simple block motion and `{#key}` swaps that only need DOM retention through an outro. Use View Transitions from `onNavigate` for snapshot morphs or page crossfades. Use GSAP for live-DOM navigation holds, interruptible sequences, split text, or scroll-linked motion. One engine per element; see [combining engines](references/page-lifetime.md#combining-engines).

## Read only what you need

- Navigation hooks and their order, outro before navigation, the lock, back and forward, scroll, focus, links, preloading, View Transitions: [SvelteKit navigation](references/sveltekit-navigation.md).
- Page reuse versus remount, layouts, `{#key}` versus `afterNavigate`, the Svelte 5 lifecycle, Svelte transitions beside GSAP, shallow-routed modals, SSR: [Page lifetime](references/page-lifetime.md).
- The five phases, GSAP setup, contexts, show and hide, layout stability, scroll, text, plugins: [Lifecycle implementation](references/motion-system.md).
- Before calling work done: [Verification](references/verification.md).

Install the [official GSAP skills](https://github.com/greensock/gsap-skills) alongside this repository. Load `gsap-core` for API details and `gsap-frameworks` for component setup only as needed.

## Rules

- GSAP runs only in the browser. `onMount` and `$effect` never run on the server; module-level code needs a `browser` guard. Scope selectors with `gsap.context` to a `bind:this` root. Clean up every tween, trigger, split, and listener in the effect teardown or the `onMount` return.
- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
- Mount, then set initial values, then paint. Users never see the settled state before the intro. Server HTML paints before hydration, so hide intro targets only under a root attribute set by an inline script, only during the initial phase, with a no-JavaScript path.
- Animate to one settled state and clear temporary styles there.
- Keep outgoing pages mounted and visible through outro and end state. Hold the navigation with `beforeNavigate` and re-issue it from the end callback, or return the outro's promise from `onNavigate`. The URL changes before `onNavigate` runs, so only the first keeps it unchanged during the outro.
- A navigation to the same route with new params updates the page in place. Run the lifecycle again from `afterNavigate` against DOM that already holds settled values, or remount with `{#key}`.
- Back and forward arrive as `popstate` through the same hooks. Never run an outro for them. Give them an intro-only path after scroll restoration.
- Do not read `page`, `data`, or `navigating` inside the effect that builds GSAP setup unless it should rebuild on every navigation.
- One engine per element. An `out:` directive on a node GSAP also animates fights it, and the block stays in the DOM until the directive finishes.
- Keep native link behavior, `data-sveltekit-*` options, focus, scroll, and no-JavaScript readability.
- Reduced motion reaches the same settled state and still fires every completion callback. Svelte transitions ignore CSS reduced-motion rules; zero them from `prefersReducedMotion`.
- Define interruption and rapid-click behavior; completion must release navigation waits exactly once.
- Verify in a real browser when practical. Use a production build for route, config, dependency, or release changes.