Upgrade guides

We try to keep breaking changes to a minimum. Code written for Framer Motion 1.0 is usually compatible with the latest version. Even so, there are times when breaking changes are unavoidable.

The easiest way to upgrade is to start with the version you're currently on and follow the guide to the next major version, and so on, until you're at the latest version.

#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 the AnimateSharedLayout component.

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 our new 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.

Check out the new reduce bundle size guide to find out how to use this new API.

import { LazyMotion, domAnimation, m } from "framer-motion"

export const MyComponent = ({ isVisible }) => (
  <LazyMotion features={domAnimation}>
    <m.div animate={{ opacity: 1 }} />
  </LazyMotion>
)

#Other breaking changes

4 also removes motion.custom(), which was previously deprecated in favour of motion().

motion.custom() had the default behaviour of forwarding all of Framer Motion's props to the underlying component. To replicate this, the forwardMotionProps option can be used.

const MotionComponent = motion(Component, {
    forwardMotionProps: true
})

#3.0

Framer Motion 3 is major release but the type of breaking change is very specific and very small. It's unlikely, though possible, to change the way your animations function.

#The changing behaviour

Motion 3 features a centralisation of how animation states are computed.

All animation props are now ranked in terms of priority (left being lowest, right being highest).

When one of those props changes, or becomes active/inactive, we will recompute the necessary animations. This is an extension and codification of a behaviour that was partially implemented only for the while props, leading to a more consistent and predictable experience.

const priority = ["animate", "while-", "exit"]

#Removing animation values

Before, if a value was outright removed from an animation prop, nothing would happen.

Now, if a value is removed, we check for it in the next highest-priority animation state. For instance, if opacity is removed from whileHover, Motion will check for it in animate and animate to that.

If we don't find one in animate, it'll check in style, or fallback to its initially-recorded value (for instance if the value was initially read from the DOM because none was explicitly defined).

#2.0

Framer Motion 2 is major release and that means there's API changes. In this guide we'll take a look at how you can upgrade your code to ensure it continues to work as expected, and highlight some features that will be broken in the new version of Motion.

#Layout animations

Framer Motion 1 supported a couple of ways to perform layout animations, the positionTransition and layoutTransition props.

// Before
<motion.div layoutTransition />

In Framer Motion 2, these have both been superseded by the layout prop.

// After
<motion.div layout />

Both of the old props used to take a transition as an argument.

// Before
<motion.div layoutTransition={{ duration: 2 }} />

Now, layout animations use the same default transition prop as other animations.

// After
<motion.div layout transition={{ duration: 2 }} />

In Framer Motion 1, layout animations could distort borderRadius and boxShadow properties on components that were changing size. This is now fixed if either property is animated.

<motion.div layout initial={{ borderRadius: 20 }} />

Layout animations that changed size could also distort child components. This can now be corrected by providing them with a layout prop, too.

Only immediate children will need to be corrected for scale.

<motion.div layout>
  <motion.div layout />
</motion.div>

#Breaking changes

There are some changes that don't have an immediate fix that you should be aware of before upgrading.

#Drag

Drag has been refactored to use the same layout projection rendering methodology that powers Motion 2's layout animations to ensure the two features are fully compatible with each other.

This has lead to some breaking changes:

• Drag listeners (like onDrag) now report the point relative to the viewport, moving in line with other pointer gestures in Motion.
• dragOriginX and dragOriginY have been removed. These were added to allow a hacky way to make positionTransition compatible with drag, but layout is compatible with drag by default.

#useAnimatedState

The useAnimatedState API was an experimental and undocumented API for use in Framer X. This has now been removed.