Skip to content
omaris

System

PageTransition

Page transitions — off unless you ask for one.

import { PageTransition } from 'omaris'
Learn

Examples

Presets

Five of the seventeen presets, off unless you ask. Change key and the content transitions; here the key is the step, so the buttons drive it.

Overview
<script lang="ts">	import { Button, PageTransition, SegmentedButton } from 'omaris';	import type { PageTransitionName } from 'omaris';​	let transition = $state<PageTransitionName>('shared-x');	let step = $state(0);​	const PANELS = ['Overview', 'Orders', 'Customers'];</script>​<div class="flex w-full max-w-lg flex-col gap-4">	<SegmentedButton		label="Preset"		bind:value={transition}		items={[			{ value: 'fade', label: 'fade' },			{ value: 'fade-through', label: 'fade-through' },			{ value: 'shared-x', label: 'shared-x' },			{ value: 'shared-y', label: 'shared-y' },			{ value: 'scale', label: 'scale' }		]}	/>​	<div class="h-32 overflow-hidden rounded-shape-lg border border-border">		<PageTransition key={step} {transition} class="h-full">			<div class="flex h-full items-center justify-center bg-surface-container-low">				<span class="text-title-md">{PANELS[step]}</span>			</div>		</PageTransition>	</div>​	<div class="flex gap-2">		<Button size="xs" variant="outlined" onclick={() => (step = (step + 2) % 3)}>Back</Button>		<Button size="xs" variant="outlined" onclick={() => (step = (step + 1) % 3)}>Forward</Button>	</div></div>

In a layout

In a real app the key is the pathname, so every navigation transitions and nothing else has to change: ``svelte <PageTransition key={page.url.pathname} transition="shared-x"> {@render children()} </PageTransition> ` direction` is worked out from the keys by default; set it by hand, as here, when the layout already knows which way it went.

/orders
<script lang="ts">	import { Button, PageTransition } from 'omaris';​	let index = $state(0);	let direction = $state<'forward' | 'backward'>('forward');​	const PAGES = ['/orders', '/orders/4021', '/orders/4021/items'];​	function go(step: number) {		direction = step > 0 ? 'forward' : 'backward';		index = Math.min(PAGES.length - 1, Math.max(0, index + step));	}</script>​<div class="flex w-full max-w-lg flex-col gap-4">	<div class="h-28 overflow-hidden rounded-shape-lg border border-border">		<PageTransition key={PAGES[index]} transition="shared-x" {direction} class="h-full">			<div class="flex h-full items-center justify-center bg-surface-container-low">				<code class="text-body-md">{PAGES[index]}</code>			</div>		</PageTransition>	</div>​	<div class="flex gap-2">		<Button size="xs" variant="outlined" disabled={index === 0} onclick={() => go(-1)}>Back</Button>		<Button size="xs" variant="outlined" disabled={index === 2} onclick={() => go(1)}>			Deeper		</Button>	</div></div>

Native stack

push is the phone's navigation stack. Forward, the new page slides in over the old one, which sits back a third of the way and dims beneath it; Back pops — the page on top slides off and the one beneath comes back up. Give it onback and a drag from the left edge pulls the page aside with the previous one tracking underneath; let go past halfway and it goes.

<script lang="ts">	import {		Button,		DeviceMockup,		IconButton,		List,		ListItem,		PageTransition,		Text,		TopAppBar	} from 'omaris';​	const ORDERS = [		{			id: '4021',			who: 'Amina Yusuf',			total: '$184.00',			items: ['Espresso beans', 'Pour-over kit']		},		{ id: '4022', who: 'Karwan Ali', total: '$42.50', items: ['Cold brew', 'Oat milk'] },		{ id: '4023', who: 'Hevi Salih', total: '$96.20', items: ['Filter papers', 'Kettle'] }	];​	/** The route, as a stack of segments: `[]`, `['4021']`, `['4021', 'Cold brew']`. */	let path = $state<string[]>([]);​	const order = $derived(ORDERS.find((entry) => entry.id === path[0]));	const item = $derived(path[1]);​	function back() {		path = path.slice(0, -1);	}</script>​{#snippet backButton()}	<IconButton aria-label="Back" onclick={back}>		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">			<path d="M15 5l-7 7 7 7" stroke-linecap="round" stroke-linejoin="round" />		</svg>	</IconButton>{/snippet}​{#snippet chevron()}	...{/snippet}​<DeviceMockup width={300}>	<PageTransition key={path.join('/')} transition="push" onback={back} class="min-h-full">		{#if !order}			<div class="flex min-h-full flex-col">				<TopAppBar size="small" title="Orders" variant="surface" />				<List class="px-2">					{#each ORDERS as entry (entry.id)}						<ListItem							headline={entry.who}							supportingText="#{entry.id} · {entry.total}"							lines={2}							onclick={() => (path = [entry.id])}						>							{#snippet trailing()}{@render chevron()}{/snippet}						</ListItem>					{/each}				</List>			</div>		{:else if !item}			<div class="flex min-h-full flex-col">				<TopAppBar size="small" title="Order #{order.id}" variant="surface">					{#snippet leading()}{@render backButton()}{/snippet}				</TopAppBar>				<div class="flex flex-col gap-4 px-4 pt-2 pb-6">					<div class="rounded-shape-lg bg-primary-container p-4 text-primary-container-foreground">						<Text variant="label-md">{order.who}</Text>						<Text variant="display-sm" tabular>{order.total}</Text>					</div>					<List class="-mx-2">						{#each order.items as name (name)}							<ListItem headline={name} onclick={() => (path = [order.id, name])}>								{#snippet trailing()}{@render chevron()}{/snippet}							</ListItem>						{/each}					</List>				</div>			</div>		{:else}			<div class="flex min-h-full flex-col">				<TopAppBar size="small" title={item} variant="surface">					{#snippet leading()}{@render backButton()}{/snippet}				</TopAppBar>				<div class="flex flex-col gap-3 px-4 pt-2 pb-6">					<div class="aspect-video rounded-shape-lg bg-surface-container-high"></div>					<Text variant="body-md" tone="muted">						In order #{order.id} for {order.who}. Swipe from the left edge, or press Back, to pop						this page off the stack.					</Text>					<Button variant="tonal" class="self-start" onclick={() => (path = [])}>						Back to orders					</Button>				</div>			</div>		{/if}	</PageTransition></DeviceMockup>

Cover and reveal

cover is a modal: forward, the page rises over the one below, which sits back and dims; Back drops it away again. reveal is the same pair the other way round, and swap lands with a small overshoot.

/orders
<script lang="ts">	import { Button, PageTransition, SegmentedButton } from 'omaris';	import type { PageTransitionName } from 'omaris';​	let transition = $state<PageTransitionName>('cover');	let index = $state(0);​	const PAGES = ['/orders', '/orders/new', '/orders/new/confirm'];​	function go(step: number) {		index = Math.min(PAGES.length - 1, Math.max(0, index + step));	}</script>​<div class="flex w-full max-w-lg flex-col gap-4">	<SegmentedButton		label="Pattern"		bind:value={transition}		items={[			{ value: 'cover', label: 'cover' },			{ value: 'reveal', label: 'reveal' },			{ value: 'slide', label: 'slide' },			{ value: 'swap', label: 'swap' }		]}	/>​	<div class="h-28 overflow-hidden rounded-shape-lg border border-border">		<PageTransition key={PAGES[index]} {transition} class="h-full">			<div class="flex h-full items-center justify-center bg-surface-container-low">				<code class="text-body-md">{PAGES[index]}</code>			</div>		</PageTransition>	</div>​	<div class="flex gap-2">		<Button size="xs" variant="outlined" disabled={index === 0} onclick={() => go(-1)}>Back</Button>		<Button size="xs" variant="outlined" disabled={index === 2} onclick={() => go(1)}>			Deeper		</Button>	</div></div>

Auto direction

direction defaults to auto, which keeps the keys it has seen as a stack: a key it has never seen plays forward, and one already on the stack plays backward and unwinds it. Click across the tabs, then back to one you have been to. A tab strip would rather set it by hand — right is forward.

Overview
Last transition played: —
<script lang="ts">	import { PageTransition, SegmentedButton, Text } from 'omaris';​	const TABS = ['Overview', 'Orders', 'Menu', 'Staff'];​	let at = $state('Overview');	let played = $state('—');</script>​<div class="flex w-full max-w-lg flex-col gap-4">	<SegmentedButton		label="Section"		bind:value={at}		items={TABS.map((tab) => ({ value: tab, label: tab }))}	/>​	<div class="h-28 overflow-hidden rounded-shape-lg border border-border">		<PageTransition key={at} transition="shared-x" class="h-full" onstart={(way) => (played = way)}>			<div class="flex h-full items-center justify-center bg-surface-container-low">				<span class="text-title-md">{at}</span>			</div>		</PageTransition>	</div>​	<Text variant="label-sm" tone="muted">Last transition played: {played}</Text></div>

When to use it

Use it for

  • Route changes that should feel like an app. In +layout.svelte, set key={page.url.pathname} and transition="shared-x". A wizard or a settings screen keys on the step instead of the URL.
  • A stack like a phone's. transition="push" slides a deeper page in over the old one, which sits back and dims beneath it, and pops it off again on the way back. Add onback and a swipe from the leading edge pulls the page aside with the previous one tracking underneath.
  • A modal flow. transition="cover" rises a page over the one below and drops it away again on Back.
  • Going back that reads as going back. direction defaults to auto, which keeps the keys it has seen as a stack, so a Back button, a breadcrumb and a swipe back all play backward with no wiring.
  • Pages of different heights. The leaving page is taken out of flow, the container clips, and the leaving page is held where it was on screen when the router resets the scroll — so the document never grows a scrollbar and the old page never jumps.
  • A keyboard that should follow. focus moves focus to the arriving page; scroll="top" resets the scroll for a key that isn't a route.

Not for

  • An app that did not ask for it → leave transition={false}, the default, which renders the children with no wrapper and no cost.
  • A section that opens and closes → Accordion, or a Svelte transition: on the block.
  • Covering a slow load → Skeleton or Progress. A transition does not hide waiting.
  • Sideways panes a finger pages between → Navigation Bar's views, which are all mounted at once. A stack only keeps the page on top.

Do

  • Pick one preset and keep it. shared-x for siblings, push for a stack, cover for a modal, shared-y, zoom or scale for parent to child, fade-through for unrelated destinations, fade or dissolve for the least motion.
  • Leave duration alone unless you disagree with the preset. push is longer than fade because it travels further.
  • Wire onback to the same thing the Back button does — history.back(), or a goto of the parent route — so a swipe and a press land in the same place. Return false from it to refuse and let the page spring back.
  • Give a stack page the surface it sits on. A stack page is opaque by default (bg-background), so the page beneath can't show through it; in a tinted pane pass classes={{ page: 'bg-surface-container-low' }}.
  • Set direction by hand only where the keys are not a stack, like a tab strip — right is forward, left is back.
  • Key on the pathname, not the whole URL, so a query-string change does not replay the page.
  • Trust the presets under RTL. shared-x, slide, push and swap read the writing direction, so forward is leftward in Arabic, and the swipe back starts from the right edge.

Don't

  • Put one in every layout. Use one, at the outermost layout that changes.
  • Wrap a TopAppBar or a NavigationDrawer in it. Only the page moves.
  • Key on an object. A new object every render is a transition every render.
  • Use it for a change inside a page, like a filter or a sort.
  • Expect the swipe back on a deep link's first page. It needs a page it was pushed over, and there isn't one.
  • Use flip twice. It draws attention to itself.

API

PageTransition

Page transitions — off unless you ask for one.

transition defaults to false, and a false transition renders the children with no wrapper, no keyed block and no cost: navigation behaves exactly as it did before this component existed. Name a pattern and the page starts moving, on the same MD3 curves the components use.

— where page is SvelteKit's $app/state, so every navigation is a new key and every key change is a transition.

It works out which way you went. direction defaults to auto, which keeps the keys it has seen as a stack: a key it has never seen is forward and goes on the stack, and a key already on it is a Back — the stack unwinds to it and the pattern plays in reverse. That is a browser Back button, a swipe back and a breadcrumb, all without the layout being told which.

A stack is a stack both ways. push forward slides the new page in over the old one, which sits back a third of the way and dims beneath it; push backward is a pop — the page on top slides off the way it came and the one beneath comes back up — not the same motion mirrored. cover rises a page over the one below and drops it away again on the way back.

The swipe back follows the finger. Give push an onback and a drag from the leading edge pulls the page aside, with the page beneath — the one it was pushed over, kept as a still picture — parallaxing up behind it. Let go past halfway, or flick, and onback is called to navigate; the real page arrives exactly where the picture was, and the transition finishes from wherever the finger left it. Let go short and the page springs back. It needs a page to go back to — a deep link's first page has nothing beneath it, so nothing happens there — and a browser that handles the edge itself, like Safari on a phone, keeps doing so: the page then plays the ordinary pop.

Seventeen patterns, each with the duration it actually wants, so duration is only there for when you disagree. Patterns that travel along the inline axis follow the writing direction, so forward is leftward in Arabic without a second preset.

The two pages are stacked in one grid cell while they cross, so nothing jumps and the scroll position doesn't lurch. The leaving page is made inert on its way out, so a click can't land on a page that's gone.

Neither page may move the document while they cross. Three things would, and all are handled here rather than left to the consumer:

- The pair's height. Stacked in one grid cell, the row is as tall as the taller of the two, so a tall page leaving a short one holds the document at the old height and then drops it — a scrollbar that appears for a few frames and goes. The leaving page is taken out of flow at its own size the moment it starts to leave, so the container is only ever the height of the page arriving. - The travel. A page translated 32px or a full width is still part of the scrollable overflow, so the axis it moves along grows a scrollbar mid-flight. The container clips while a transition is running and stops clipping the moment it ends, so a menu or a sticky header that overflows on purpose is unaffected the rest of the time. - The scroll reset. A router puts the scroll back to the top as the new page arrives, which would yank the leaving page up to its own top mid-flight. The leaving page is held where it was on screen instead, so what slides away is what you were looking at.

import { PageTransition } from 'omaris'
<PageTransition key={page.url.pathname} transition="push">  {@render children()}</PageTransition>

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
No description in the source yet.
page
No description in the source yet.
snapshot
The page beneath a swipe back: a still picture of it, as it was.

Props

key
unknown

Change this to run a transition — page.url.pathname, usually.

transition

Defaults to false

PageTransitionName | false

The pattern, or false (the default) for none at all.

direction

Defaults to 'auto'

PageTransitionDirection | 'auto'

Which way the axis patterns travel. auto, the default, reads it off the keys it has seen: a new one is forward, one it has been to before is a Back. Set it by hand where the keys are not a stack — a tab strip, where right is forward and left is back.

duration
number

Total time for the pair, in ms. Defaults to what the pattern wants.

clip

Defaults to true

boolean

Clip the travel while a transition runs. On unless a page has something that has to escape the container mid-flight.

scroll

Defaults to 'keep'

'keep' | 'top'

Put the scroll back to the top as the new page arrives. 'top' scrolls the nearest scrollable ancestor, which is the app frame in a dashboard and the window on an ordinary page. A router does this on its own, so it is for a key that isn't a route.

focus

Defaults to false

boolean

Move focus to the arriving page, the way a native screen change does, so a keyboard lands on the new page rather than back at the top of the document.

onback
() => unknown

Go back. Setting this turns on the swipe back for push and slide: a drag from the leading edge pulls the page aside and, let go past halfway or flicked, calls this to navigate — history.back(), or a goto of the parent route. Return false, or a promise of it, to refuse and let the page spring back; anything else is a yes.

swipe

Defaults to 'edge'

'edge' | 'anywhere'

Where a swipe back may start. edge, the default, is the 32px along the leading edge, the way a phone does it; anywhere lets a sideways drag from any point on the page go back, which suits a page with no sideways scrolling of its own.

onstart
(direction: PageTransitionDirection) => void

Called as a pair starts, with the direction it is playing.

onend
() => void

Called once the pair has landed.

children required
Snippet

The page.

class
string
classes
PageTransitionClasses

Per-part Tailwind overrides. class still covers the root.