sveltekit-view-transition

Use create-svelte to scaffold a new SvelteKit project. You can either initialize the project in the current directory or specify a new directory name.

# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

The list-and-details example is a Svelte project powered by create-svelte. To get started, create a new SvelteKit project using the following commands:

# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

To enable view transitions for all navigations in your application, call setupViewTransition() within your root layout file (e.g., src/routes/+layout.svelte). This provides a baseline transition for every page change.

<script>
	import { setupViewTransition } from 'sveltekit-view-transition';

	setupViewTransition();
</script>

<slot />

After creating the project and installing dependencies (via npm install, pnpm install, or yarn), use the following commands to manage the application lifecycle:

• Development: Start a local development server.
• Production Build: Compile the application for production.
• Preview: Run a local server to preview the production build.

# Start development server
npm run dev

# Start development server and open in browser
npm run dev -- --open

# Build for production
npm run build

# Preview production build
npm run preview

After creating the project and installing dependencies (npm install, pnpm install, or yarn), use the following scripts to manage the application lifecycle:

Development

Start the development server:

npm run dev

To start the server and automatically open the app in a new browser tab:

npm run dev -- --open

Production

Build the application for production:

npm run build

To preview the production build locally:

npm run preview

Note: To deploy, you may need to install a SvelteKit adapter for your target environment.

Install the library as a development dependency using your preferred package manager.

npm i -D sveltekit-view-transition@latest  # or pnpm/yarn

You can customize the default root transition by targeting the ::view-transition-old(root) and ::view-transition-new(root) pseudo-elements in your global CSS.

To disable the default crossfade, set view-transition-name: none on the :root. To change the animation speed, adjust the animation-duration.

<script>
	import { setupViewTransition } from 'sveltekit-view-transition';

	setupViewTransition();
</script>

<slot />

<style>
	/* Disable default crossfade. */
	:root {
		view-transition-name: none;
	}

	/* Or, just modify the duration. */
	:global(::view-transition-old(root)),
	:global(::view-transition-new(root)) {
		animation-duration: 2s;
	}
</style>

Instead of passing a simple string, you can pass an object to the transition action to customize how view transitions are applied. This allows for conditional logic based on navigation state, viewport visibility, and specific element properties.

Supported options:

• name (required): The view-transition-name. Can be a string or a function.
• classes: Classnames applied to the target element during transition. Can be an array of strings or a function returning an array.
• applyImmediately: Whether the transition name is applied immediately or only during navigation. Can be a boolean or a function.
• shouldApply: Whether the transition should be applied at all. Can be a boolean or a function.

<div use:transition={{ 
  name: 'my-element', 
  classes: ['active'], 
  applyImmediately: true, 
  shouldApply: true 
}}></div>

The classes function, returned by setupViewTransition, allows you to add specific CSS classes to the :root element during a navigation. This is useful for styling the transition state globally.

It can be called directly in a Svelte <script> tag. It accepts either:

1. An array of strings.
2. A function that returns an array of strings. This function receives a navigation object (similar to the one provided by the transition action).

By default, classes is wrapped in afterNavigate to ensure it works during same-page navigation. You can pass false as a second parameter to disable this wrapping.

<script>
	import { setupViewTransition } from 'sveltekit-view-transition';

	const { classes } = setupViewTransition();

	classes(({ navigation }) => {
		if (navigation.to?.route.id === '/') {
			return ['back'];
		}
	});
</script>

To give specific elements unique view transitions (allowing them to morph or animate independently during navigation), use the transition action returned by setupViewTransition().

Pass a string to the use:transition directive; this string becomes the element's view-transition-name. You can then target this specific transition in your CSS using ::view-transition-old(<name>) and ::view-transition-new(<name>).

<script>
	import { setupViewTransition } from 'sveltekit-view-transition';

	const { transition } = setupViewTransition();
</script>

<header use:transition={'header'}>
	<!-- links -->
</header>

<slot />

<style>
	:global(::view-transition-old(header)),
	:global(::view-transition-new(header)) {
		/* ... */
	}
</style>

The off function allows you to manually unsubscribe a specific handle from a specific event. While on returns an unsubscribe function that is usually preferred, off is available for manual management.

By default, off is wrapped in afterNavigate to handle same-page navigation. You can pass false as a second parameter to avoid this wrapping.