System
PageTransition
Page transitions — off unless you ask for one.
import { PageTransition } from 'omaris' 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.
<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.
9:41
<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.
<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, setkey={page.url.pathname}andtransition="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. Addonbackand 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.
directiondefaults toauto, 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.
focusmoves 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-xfor siblings,pushfor a stack,coverfor a modal,shared-y,zoomorscalefor parent to child,fade-throughfor unrelated destinations,fadeordissolvefor the least motion. - Leave
durationalone unless you disagree with the preset.pushis longer thanfadebecause it travels further. - Wire
onbackto the same thing the Back button does —history.back(), or agotoof the parent route — so a swipe and a press land in the same place. Returnfalsefrom 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 passclasses={{ page: 'bg-surface-container-low' }}. - Set
directionby 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,pushandswapread 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
TopAppBaror aNavigationDrawerin 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
fliptwice. 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.