Edit Page

#Upgrade to Motion 2

How to upgrade Framer Motion from 1.x to 2.x

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.