Upgrade Motion automatically with the Motion AI Kit, or follow the manual steps in this guide.
We strive to reduce the number of breaking API changes but they are occasionally necessary.
Upgrade with AI
Install the Motion AI Kit and run:
/motion upgradeYour agent will handle the rest.
Manual upgrade instructions
For manual upgrade, start with the major version you're currently using, then follow the guide to upgrade to the next version, and so on until you're at the latest version.
Changes between major versions are usually small so this is usually a quick process.
14.0
There are no breaking changes in Motion for React in version 14.
This release deprecates some internal APIs. It also introduces stricter versioning between Motion's internal dependencies.
13.0
To improve compatibility across different build systems, Motion 13.0 removes @emotion/is-prop-valid as an optional dependency in favour of explicit injection.
This primarily affects users of CSS-in-JS libraries Styled Components and Emotion.
If, after upgrade, you find styled motion components now rendering props to the DOM that would previously be filtered out, you can either:
- Manually provide
@emotion/is-prop-validto Motion viaMotionConfig.
import isPropValid from "@emotion/is-prop-valid"
import { MotionConfig } from "motion/react"
<MotionConfig isValidProp={isPropValid}>
<App />
</MotionConfig>- Reverse the composition so the styling library controls DOM prop forwarding:
const StyledDiv = styled.div`
/* styles */
`
const MotionDiv = motion.create(StyledDiv)When using Styled Components 6, use transient props or configure shouldForwardProp to prevent styling props reaching the DOM.
12.0
There are no breaking changes in Motion for React in version 12. Please see the JavaScript upgrade guide for changes to the vanilla JS API.
"motion/react"
To upgrade to Motion for React, uninstall framer-motion and install motion:
npm uninstall framer-motion
npm install motionThen simply swap imports from "framer-motion" to "motion/react":
import { motion } from "motion/react"11.0
Velocity calculation changes
In previous versions, setting a MotionValue multiple times within the same animation frame would update the value's velocity:
const x = motionValue(0)
requestAnimationFrame(() => {
x.set(100)
x.getVelocity() // Velocity of 0 -> 100
x.set(200)
x.getVelocity() // Velocity of 100 -> 200
})This behaviour is incorrect. Synchronous code, practically speaking for the purposes of animation, should be considered instantaneous. Therefore, in the above example, x was only 100 for a infinitely small amount of time. It essentially never happened.
From version 11, subsequent value updates within synchronous blocks of code won't be considered part of a MotionValue's velocity calculations. Therefore, if getVelocity is called after the second update, velocity will be calculated between the latest value and the value at the end of the previous frame.
const x = motionValue(0)
requestAnimationFrame(() => {
x.set(100)
x.getVelocity() // Velocity of 0 -> 100
x.set(200)
x.getVelocity() // Velocity of 0 -> 200
})Render scheduling changes
In previous versions, motion components trigger a render synchronously after mount to ensure dynamically-calculated values are updated on-screen. This process has now been moved to a microtask.
This ensures that if a component is synchronously re-rendered by a useLayoutEffect, the first render is swallowed and we only apply the final one (the one that will be used on-screen).
This is better for performance and in most cases won't have practical ramifications for you as a developer. However, there is a caveat for Jest tests. Previously it could be assumed that updates would have applied synchronously.
render(
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
transition={{ false }}
/>
)
expect(element).toHaveStyle("opacity: 1")Tests like this should be updated to await an animation frame.
render(
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
transition={{ false }}
/>
)
await nextFrame()
expect(element).toHaveStyle("opacity: 1")
// utils.js
import { frame } from "framer-motion"
export async function nextFrame() {
return new Promise<void>((resolve) => {
frame.postRender(() => resolve())
})
}10.0
IntersectionObserver fallback
This version removes the IntersectionObserver fallback behaviour for whileInView.
IntersectionObserver is supported by all modern browsers, representing over 99% of visitors to sites built in Framer. If you require support for legacy browsers like Internet Explorer or Safari 12, we recommend adding an IntersectionObserver polyfill.
AnimatePresence exitBeforeEnter prop
This prop was deprecated in 7.2.0. Usage will now throw an error with upgrade instructions (swap to mode="wait").
9.0
This version makes tap events keyboard-accessible.
As a result, all elements with tap listeners or whileTap will receive tabindex="0". Reverting this behaviour is discouraged, but can be achieved by passing tabIndex={-1}.
Additionally, whileFocus now behaves like :focus-visible rather than :focus. Loosely, this means that elements receiving focus via pointer won't trigger focus animations, with the exception of input elements which will trigger focus from any input.
8.0
Framer Motion uses pointer events to detect tap, drag and hover gestures. In previous versions, these were polyfilled with mouse and touch events in legacy browsers. Version 8 removes this polyfill.
As a result, while DragControls.start was always only documented to work with events from onPointerDown, it was typed to also accept onMouseDown and onTouchStart events. These will now throw a type error for TypeScript users and should be converted to onPointerDown.
7.0
Framer Motion 7 makes react@18 the minimum supported version.
Framer Motion 3D users should also upgrade React Three Fiber to ^8.2.2.
6.0
Framer Motion 3D now lives in the framer-motion-3d package. So to upgrade to 6.0 simply change imports from "framer-motion/three" to "framer-motion-3d".
5.0
Shared layout animations
Framer Motion 5 removes need for using the AnimateSharedLayout component when performing shared element animations.
Now, you can use the layoutId prop and components will animate from one to another without the need for the AnimateSharedLayout wrapper.
Measuring layout changes
Layout changes are detected when a component with a layout or layoutId prop re-renders. But it isn't performant to measure all components when just one changes.
AnimateSharedLayout could be used to group components that affected each other's layout. When one rerendered, AnimateSharedLayout would force them all to rerender.
This was not a performant approach because all grouped components would perform a re-render. Now, components that affect each other's layout can be grouped with LayoutGroup:
import { LayoutGroup, motion } from "framer-motion"
export function App() {
return (
<LayoutGroup>
<Submenu />
<Submenu />
</LayoutGroup>
)
}
function Submenu({ children }) {
const [isOpen, setIsOpen] = useState(false)
return (
<motion.ul
layout
style={{ height: isOpen ? "auto" : 40 }}
>
{children}
</motion.ul>
)
}Grouped components will be measured whenever one of them renders, but they won't be forced to render themselves.
Scoped layout animations
Previously, because AnimateSharedLayout was required, it would naturally scope shared layout animations. So animating between components with the same layoutId would only happen within the same AnimateSharedLayout:
/**
* These items share the same layoutId but won't animate
* between each other because they're children of different
* AnimateSharedLayout components.
*/
<>
<AnimateSharedLayout>
{isVisible ? <motion.div layoutId="modal" /> : null}
</AnimateSharedLayout>
<AnimateSharedLayout>
{isVisible ? <motion.div layoutId="modal" /> : null}
</AnimateSharedLayout>
</>This could lead to very poor performance. AnimateSharedLayout reduces layout thrashing within itself by batching layout measurements. But it had no way of batching between many AnimateSharedLayout components. The more you add, the more layout thrashing will occur.
Now, there is one global tree throughout your app so all layout measurements are batched. But this means all layoutIds share the same global context. To bring back this old behaviour you can namespace layoutId by providing a id prop to LayoutGroup:
/**
* These layoutIds are now namespaced with
* the id provided to LayoutGroup.
*/
<>
<LayoutGroup id="a">
{isVisible ? <motion.div layoutId="modal" /> : null}
</LayoutGroup>
<LayoutGroup id="b">
{isVisible ? <motion.div layoutId="modal" /> : null}
</LayoutGroup>
</>Drag to reorder
Previous drag-to-reorder implementations were ad-hoc, usually adapted from an old proof-of-concept sandbox that relied on the (now removed) onViewportBoxUpdate prop. These solutions should be reimplemented with the new Reorder components.
ESM and create-react-app
To enable Framer's experimental "Handshake" features, that allow you to publish no-code components straight from Framer into production, we've moved Framer Motion to ESM modules. Some build environments like create-react-app might have some trouble mixing ES modules (like Framer Motion) and CJS modules (like React).
To fix, either upgrade to create-react-app@next, or downgrade to framer-motion@4.1.17.
4.0
Framer Motion 4 introduces a brand new LazyMotion component to help reduce bundle size.
Previously, a subset of motion functionality could be loaded in synchronously or asynchronously via MotionConfig's features prop. This functionality has been removed in favour of the new LazyMotion component.