GSAP SvelteKit

Every animated page or component runs through the same lifecycle:

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

Mount and unmount belong to Svelte. The five phases between them belong to your animation code and happen while the node exists. This skill covers getting those phases right when SvelteKit's router decides when pages mount, update in place, and unmount: navigation timing, page reuse, interruptions, and cleanup. The user's request and the existing design decide how things look.

SvelteKit reuses components across navigation. A +page.svelte that stays on the same route with new params updates in place, and layouts persist through every child navigation. Treat a param change as a new page lifecycle even though nothing mounts. See Page lifetime.

Start with the project

1. Read repository instructions and the current code.
2. 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.
3. 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).
4. 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.
5. Look at layouts, navigation components, global CSS, accessibility conventions, tests, and any motion already in use: Svelte transition: directives, svelte/animate, a View Transitions setup, or GSAP.
6. Keep the project's package manager, language, file layout, styling, and component conventions.

Add GSAP or a plugin only when the requested motion needs it. Do not replace an animation library the project already chose unless asked.

Pick GSAP, Svelte transitions, or View Transitions per effect

Three engines can animate a navigation. Choose per effect, one engine per element. Use Svelte transition:, in:, and out: for:

• A block that appears and disappears with a fade, fly, or slide and gates nothing on completion.
• A page swap inside {#key} where holding the old page until its out: finishes is the whole effect.

They keep the outgoing block mounted until every outro ends, reverse cleanly, and need no lifecycle code.

Use View Transitions, started from onNavigate, for a shared element that morphs between two routes or a whole-page crossfade or slide keyed by a class on html. They need no lifecycle code beyond the hook and fall back to an instant swap in unsupported browsers.

Use GSAP when the effect needs:

• An outro that finishes on the live outgoing page while the router waits.
• Interruption, reversal, or scrubbing mid-transition. A view transition is a fixed pair of snapshots; a directive reverses only itself.
• Sequenced timing across many targets, split text, or scroll-linked progress.
• A completion callback that gates navigation, focus, or removal.

Mixing across elements is fine: the browser morphs one image while GSAP animates the rest, or an out: holds a block while GSAP works inside it. Never give one element to two engines in the same transition. See Combining engines.

Follow the requested motion

The user's request decides effects, direction, timing, easing, and intensity. Map it onto the five phases without changing the look. For anything unspecified, keep the project's existing convention or pick a quiet default.

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.
• Page reuse versus remount, layouts, {#key} versus afterNavigate, the Svelte 5 lifecycle, Svelte transitions beside GSAP, shallow-routed modals, SSR: Page lifetime.
• The five phases, GSAP setup, contexts, show and hide, layout stability, scroll, text, plugins: Lifecycle implementation.
• Before calling work done: Verification.

The official GSAP skills (gsap-core, gsap-frameworks, gsap-timeline, gsap-scrolltrigger, gsap-plugins, gsap-utils, gsap-performance) cover the GSAP API and the onMount, gsap.context, and cleanup pattern inside one Svelte component. This skill covers how GSAP fits SvelteKit's router.

Pieces to add, only as needed

• One browser-only module that registers GSAP and plugins, guarded by browser from $app/environment.
• A route transition controller in the root +layout.svelte, the one component that outlives every navigation, with one stable route container around {@render children()}.
• beforeNavigate with cancel() and a guarded goto as the hold, when the outro must finish with the URL unchanged, or onNavigate returning the outro's promise when a URL that leads the animation is acceptable.
• afterNavigate in pages or the controller to start intros, compared on pathname so param and search changes do not replay them.
• bind:this refs or data attributes marking the elements a page animates.
• A controller per page or component that owns its five phases.
• Intro and outro timeline builders.
• A presence controller when conditional content must stay mounted through a GSAP outro, or an out: directive on the block when that is the whole effect.

Persistent header, nav, and footer live in the layout outside the route container. A component owns its own lifecycle; the layout controller owns page lifecycles.

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.
• Lay out the final page with normal CSS first. One stable wrapper owns the geometry through every phase.
• 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.
• Prepare incoming targets before revealing the swap. Never flash settled or stale content.
• Reduced motion reaches the same settled state and still fires every completion callback. Svelte transitions ignore CSS reduced-motion rules; zero them from prefersReducedMotion.
• Prefer transforms and autoAlpha. Set will-change only while animating, then clear it.
• Use timelines for sequences. Decide up front what happens on rapid clicks and interrupted animations.
• Verify in a real browser when practical. Use a production build for route, config, dependency, or release changes.