motion-layout-animations
Motion layout animation internals - layoutId, layoutGroup, FLIP mechanism, NodeStack promote/relegate, scale correction. Use when implementing shared element transitions, debugging layout animations,
SKILL.mdskills/motion-layout-animations/SKILL.md
GitHubMotion Layout Animations
Deep technical reference for Motion's layout animation system.
Core Concepts
FLIP Principle
Layout animations use FLIP (First, Last, Invert, Play):
- First: Snapshot element's current position/size
- Last: Let browser reflow to new position/size
- Invert: Apply inverse transform to visually restore old position
- Play: Animate transform back to identity (new position)
Motion implements this via the projection system - a tree of ProjectionNodes that track layout changes and compute compensating transforms.
Key Components
| Component | Purpose |
|---|---|
ProjectionNode |
Tracks element layout, computes deltas |
NodeStack |
Manages multiple nodes sharing a layoutId |
DocumentProjectionNode |
Global root, stores all sharedNodes |
LayoutGroup |
Adds prefix to layoutId, creates isolated namespaces |
layoutId: Shared Element Transitions
How It Works
When an element with layoutId mounts:
1. registerSharedNode(layoutId, node)
2. stack.add(node)
3. node.promote() ← immediately becomes lead
└── prevLead.updateSnapshot()
└── node.snapshot = prevLead.snapshot ← inherits position
└── prevLead.hide() (if crossfade=false)
4. node animates FROM prevLead's snapshot TO its own layout
Key insight: The NEW element animates. The old element is hidden (visibility: hidden) and still occupies space.
Typical Usage
// No AnimatePresence needed for basic shared transition
{
isExpanded
? (
<motion.div layoutId="card" className="expanded">
<motion.div layoutId="title">Title</motion.div>
<motion.div layoutId="content">Content</motion.div>
</motion.div>
)
: (
<motion.div layoutId="card" className="collapsed">
<motion.div layoutId="title">Title</motion.div>
</motion.div>
);
}
card,title,contenteach get their ownNodeStack- When switching, new elements inherit snapshots from old ones
- Old elements hidden via
visibility: hidden(still occupy layout space)
Lead/Follow Mechanism
NodeStack.members: [A, B, C] ← C is lead (last registered)
↑
lead
Promote (new element becomes lead):
prevLead = leadlead = newNodenewNode.snapshot = prevLead.snapshotnewNode.resumeFrom = prevLead
Relegate (lead exits, find replacement):
- Iterate backwards from lead's index
- First node with
isPresent !== falseandisConnectedbecomes new lead
See internals.md for code.
layout: Single Element Transitions
How It Works
<motion.div layout style={{ justifySelf: isRight ? "end" : "start" }}>
Item
</motion.div>;
When CSS causes position/size change:
willUpdate()→ snapshot current layout- Browser reflows
didUpdate()→ measure new layout, compute delta- Apply inverse transform, animate to identity
layout Prop Values
| Value | Behavior |
|---|---|
true / "position" |
Animate position changes |
"size" |
Animate size changes |
"preserve-aspect" |
Maintain aspect ratio during animation |
Parent Transform Compensation
Child elements with layout automatically compensate for parent's transform:
<motion.div layoutId="container">
<motion.div layout>Title</motion.div> {/* Won't stretch with parent */}
</motion.div>;
Without layout, children would be visually stretched by parent's scale transform.
LayoutGroup: Namespace Isolation
How It Works
LayoutGroup provides a LayoutGroupContext with an id that prefixes all child layoutIds:
<LayoutGroup id="sidebar">
<motion.div layoutId="item" /> {/* actual layoutId: "sidebar-item" */}
</LayoutGroup>
<LayoutGroup id="main">
<motion.div layoutId="item" /> {/* actual layoutId: "main-item" */}
</LayoutGroup>
These two layoutId="item" elements don't share a NodeStack because their prefixed IDs differ.
Nested Groups
<LayoutGroup id="app">
<LayoutGroup id="panel">
<motion.div layoutId="card" /> {/* layoutId: "app-panel-card" */}
</LayoutGroup>
</LayoutGroup>;
See internals.md for implementation.
Scale Correction: Why borderRadius Must Be in style
The Problem
FLIP uses transform: scale() to animate size changes. But borderRadius in pixels gets visually stretched:
Original: 100x100 box, borderRadius: 10px (10%)
Scaled 2x via transform: 200x200 visual, but borderRadius looks like 20px (still 10%)
↑ corners appear stretched
The Solution
Motion's scaleCorrectors convert pixel values to percentages relative to target box:
// packages/motion-dom/src/projection/styles/scale-border-radius.ts
correct: ((latest, node) => {
const x = pixelsToPercent(latest, node.target.x);
const y = pixelsToPercent(latest, node.target.y);
return `${x}% ${y}%`;
});
Why style Prop Required
Motion only tracks values in latestValues (from style prop or initial read). The isForcedMotionValue check forces these properties into the motion value system when layout/layoutId is present:
// Simplified from is-forced-motion-value.ts
function isForcedMotionValue(key, props) {
return scaleCorrectors[key] && (props.layout || props.layoutId !== undefined);
}
Affected properties: borderRadius, borderTopLeftRadius, etc., boxShadow
If you put borderRadius only in CSS class, Motion can't track or correct it during FLIP animation.
See internals.md for full implementation.
Hidden Elements and Layout Space
When an element becomes prevLead (follower):
// stack.promote()
if (node.options.crossfade === false) prevLead.hide();
hide() sets visibility: hidden:
// applyProjectionStyles
if (!this.isVisible) {
targetStyle.visibility = "hidden";
return;
}
Important: visibility: hidden still occupies layout space. The old element remains in DOM, invisible but affecting layout, until:
- Animation completes and
safeToRemove()is called (with AnimatePresence) - Or React unmounts it (without AnimatePresence)
AnimatePresence Integration
Without AnimatePresence:
- Old element unmounted immediately by React
- New element animates from old snapshot
- Only new element visible during animation
With AnimatePresence:
- Old element kept in DOM via
PresenceChild - Both elements visible → crossfade possible
relegate()called whenisPresentbecomes falsesafeToRemove()defers actual unmount until animation completes
<AnimatePresence>
{items.map((item) => <motion.div key={item.id} layoutId={item.id} exit={{ opacity: 0 }} />)}
</AnimatePresence>;
Common Patterns
Shared Container Transition
function ExpandableCard({ isExpanded }) {
return (
<motion.div
layoutId="card"
style={{ borderRadius: 12 }} // Must be in style for scale correction
className={isExpanded ? "expanded" : "collapsed"}
>
<motion.h2 layoutId="title" layout>
Title
</motion.h2>
{isExpanded && (
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
Extra content
</motion.div>
)}
</motion.div>
);
}
List Reordering
function ReorderableList({ items }) {
return (
<Reorder.Group values={items} onReorder={setItems}>
{items.map((item) => (
<Reorder.Item key={item.id} value={item} layoutId={item.id}>
{item.label}
</Reorder.Item>
))}
</Reorder.Group>
);
}
Isolated Sections
<LayoutGroup id="sidebar">
{sidebarItems.map(item => (
<motion.div key={item.id} layoutId={item.id} layout />
))}
</LayoutGroup>
<LayoutGroup id="content">
{contentItems.map(item => (
<motion.div key={item.id} layoutId={item.id} layout />
))}
</LayoutGroup>
Debugging Tips
Check actual layoutId: If using
LayoutGroup, the real ID has prefix. LogvisualElement.projection.options.layoutId.Verify NodeStack: Check
projection.root.sharedNodes.get(layoutId)to see all members.borderRadius not animating: Ensure it's in
styleprop, not just CSS class.Elements not matching across Portal:
layoutIdmatching is global (viaDocumentProjectionNode), but verify IDs aren't prefixed differently.Unexpected layout shifts: Hidden elements (
visibility: hidden) still occupy space. Check if old elements are lingering.
Additional Resources
- internals.md - Detailed code references with line numbers