Using layoutId for Shared‑Element Animations in Framer Motion

Use layoutId to animate shared‑element transitions

Add the layoutId prop to two motion elements that should be treated as the same visual item. When the ids swap between renders, Framer Motion automatically animates the position and size change, giving a smooth shared‑element effect.

How layoutId works

Framer Motion keeps an internal map of elements by their layoutId. On each render it compares the previous layout (size and position) of the element with that id to the current layout of the element now bearing the same id. If a match is found, it computes a delta and animates the element from the old layout to the new one using the supplied transition.

Worked example

The following React snippet shows a gallery of two images that exchange their layoutId when clicked. Wrapping the images in AnimatePresence ensures the exiting image is animated out instead of being removed instantly.

import { motion, AnimatePresence } from 'framer-motion';
import { useState } from 'react';

export default function Gallery() {
  const [leftId, setLeftId] = useState('img-a');
  const [rightId, setRightId] = useState('img-b');

  const handleClick = () => {
    setLeftId(prev => (prev === 'img-a' ? 'img-b' : 'img-a'));
    setRightId(prev => (prev === 'img-b' ? 'img-a' : 'img-b'));
  };

  return (
    
      
        
        
      
    
  );
}

Run this code in a React project that has framer-motion version 4.0 or later installed. No special permissions are required; the component mounts in the browser like any other React element.

Limits and common mistakes

• HTML only: layoutId works on regular DOM elements (e.g., div, img). It does not animate SVG path data or custom canvas drawings.
• DOM presence: The element must stay in the DOM for the duration of the animation. Removing it before the animation finishes (e.g., forgetting AnimatePresence) causes the layout shift to be skipped.
• Excessive swaps: Rapidly changing layoutId on many items can trigger layout thrash, leading to dropped frames on low‑end devices. Keep swaps to user‑driven actions or infrequent state changes.
• Size‑change jarring: If an element goes from hidden (size 0) to full‑screen, the sudden layout shift can feel abrupt. Mitigate by also animating opacity or scale alongside layoutId.

How to verify the result

1. Open the page in a browser and open DevTools → Performance.
2. Record a short session while clicking the gallery to swap images.
3. Look for a single Layout Shift entry whose duration matches the animation (e.g., ~300 ms with the spring settings).
4. Visually confirm that both images glide along a shared path without flickering or jumping.
5. If the shift appears instant, check that the layoutId values are actually swapped in the React state and that AnimatePresence wraps the images.