Shared element transition
Also called hero animation, magic move, or shared layout animation
A transition where an element from one view, like a thumbnail, travels and grows into its place in the next view, linking the two screens.
import { useState } from 'react';
import { Dialog } from '@base-ui/react/dialog';
import { AnimatePresence, motion } from 'motion/react';
const photos = [
{ id: 'harbor', title: 'Harbor at dawn' },
{ id: 'dunes', title: 'Desert dunes' },
{ id: 'lagoon', title: 'Glacier lagoon' }
];
type Photo = (typeof photos)[number];
// The thumbnail and the large image share a layoutId, so Motion flies one into the other.
function PhotoImage({ photo }: { photo: Photo }) {
return (
<motion.img
layoutId={photo.id}
layoutCrossfade={false}
transition={{ type: 'spring', bounce: 0, duration: 0.4 }}
src={`/photos/${photo.id}.jpg`}
alt={photo.title}
style={{ borderRadius: 12 }}
className='aspect-square w-full object-cover'
/>
);
}
export function PhotoGallery() {
const [open, setOpen] = useState<Photo | null>(null);
return (
<Dialog.Root open={open !== null} onOpenChange={() => setOpen(null)}>
<div className='grid w-96 grid-cols-3 gap-3'>
{photos.map((photo) => (
<button key={photo.id} type='button' onClick={() => setOpen(photo)}>
<PhotoImage photo={photo} />
</button>
))}
</div>
<AnimatePresence>
{open && (
<Dialog.Portal keepMounted>
<Dialog.Backdrop className='fixed inset-0 bg-black/40 transition-opacity duration-300 data-ending-style:opacity-0 data-starting-style:opacity-0' />
{/* The exit fade also tells Base UI to wait before hiding the popup. */}
<Dialog.Popup
render={<motion.div exit={{ opacity: 0 }} />}
className='fixed top-1/2 left-1/2 w-80 max-w-[calc(100vw-2rem)] -translate-1/2'
>
<PhotoImage photo={open} />
<div className='mt-2 flex items-center justify-between rounded-xl bg-background p-4 transition-[opacity,translate] duration-300 starting:translate-y-2 starting:opacity-0'>
<Dialog.Title className='font-medium'>
{open.title}
</Dialog.Title>
<Dialog.Close className='text-sm underline'>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
)}
</AnimatePresence>
</Dialog.Root>
);
}In the photo grid, when a thumbnail is clicked, expand it into a detail card with a shared element transition: the image grows from its grid position to the top of the card over about 400ms with a spring (no bounce) while the card text fades in. Closing with the close button, the Escape key, or a click outside should shrink the image back into its tile. Use Motion’s layoutId for the image and the title.
Paste into Layerwise or any AI coding tool.
What is Shared element transition?
In a shared element transition, the same item appears on two screens, and the change between them animates that item from its old position and size to its new one. Tap a photo in a grid and it expands into the large photo on the detail view; close it and it shrinks back into its tile. The rest of the screen usually fades around it.
It helps people keep their place, because they can see where the detail view came from and where it will return. It is common in photo galleries, product grids, music apps, and any list that opens into a detail view. Flutter calls it a Hero animation, and Keynote calls a similar effect Magic Move.
On the web, Motion does this with layoutId: give the thumbnail and the detail image the same ID, and Motion animates between them when one replaces the other. The browser’s View Transitions API does the same with view-transition-name. Keep it around 300 to 500ms, and make sure closing lands the element exactly back in its tile.
Often confused with
- Morph
- A morph reshapes one element in place. A shared element transition carries an element from one view to another.
Related terms
All termsLayout animation
An animation that smoothly moves and resizes elements when the layout changes, such as list items gliding to new spots after a sort or filter.
View Transitions API
A browser feature that animates between two states of a page by snapshotting the old view, applying your update, and animating to the new one.
Page transition
An animation that plays when you move from one page or screen to another, such as the old page fading out as the new one fades in.
Spatial consistency
Moving elements in ways that match where things live in the interface, so people can tell where an item went and how to find it again.
Build it with Layerwise
Describe your app, watch it run in a live preview, and publish it with a database, storage, and sign-in built in.