Everything about Framer Motion layout animations

Layout animations fundamentals

Before we dive into the new features and complex examples of layout animations, let's look back at the fundamentals to reacquaint ourselves with how they work.

A brief refresher on layout animations

In Framer Motion, you can animate a motion component between distinct layouts by setting the layout prop to true. This will result in what we call a layout animation.

We can't animate a motion component between layouts using a combination of initial and animate props as we would do for other kinds of Framer Motion animations. For that, we need to use the layout prop.

In the example below, you'll find a first showcase of a layout animation:

• You can change the position of the motion component, the square, along the x axis.
• You can enable or disable the layout prop for that motion component

1
// position: start
2
    
3
<motion.div
4
  style={{
5
    justifySelf: position,
6
  }}
7
  //...
8
/>
9

We can see that each time we change the layout, i.e. a rerender occurs, the layout prop allows for the component to transition smoothly from its previous layout to the newly selected one. However, without it there is no transition: the square will move abruptly.

Layout animations "smooth things up", and add a certain level of physicality to some user interactions where usually things would transition abruptly. One example where they can shine is when adding/removing elements from a list. I tend to leverage layout animations a lot for use cases like this one, especially combined with other Framer Motion features such as AnimatePresence.

The playground below showcases one of my own NotificationList component that leverages layout animations:

• each notification is wrapped in a motion component with the layout prop set to true.
• the overall list is wrapped in AnimatePresence thus allowing each item in a list to have an exit animation.
• clicking on any of the notifications on the list will remove them and, thanks to layout animations, the stack will gracefully readjust itself.

import { motion, AnimatePresence } from 'framer-motion';
import React from 'react';
import { Wrapper, Toast } from './Components';
import './scene.css';

const ITEMS = ['Welcome 👋', 'An error occurred 💥', 'You did it 🎉!', 'Success ✅', 'Warning ⚠️'];

const Notifications = () => {
  const [notifications, setNotifications] = React.useState(ITEMS)

  return (
    <Wrapper> 
      <AnimatePresence>
        {notifications.map((item) => 
            <motion.div
              key={item}
              onClick={() => setNotifications((prev) => prev.filter(notification => notification !== item))}
              layout
              initial={{
                y: 150,
                x: 0,
                opacity: 0,
              }} 
              animate={{
                y: 0,
                x: 0,
                opacity: 1,
              }}
              exit={{
                opacity: 0,
              }}
            >
              <Toast>{item}</Toast>
            </motion.div> 
        )}   
      </AnimatePresence>
    </Wrapper>
  );
}

export default Notifications

Fixing distortions

When performing a layout animation that affects the size of a component, some distortions may appear during the transition for some properties like borderRadius or boxShadow. These distortions will occur even if these properties are not part of the animation.

Luckily, there's an easy workaround to fix those: set these properties as inline styles as showcased below:

1
// expanded: false
2

3
// CSS
4
.box {
5
  width: 20px;
6
  height: 20px;
7
  border-radius: 20px;
8
}
9

10
.box[data-expanded="true"] {
11
  width: 150px;
12
  height: 150px;
13
}
14
  
15
// JS
16
<motion.div
17
  layout
18
  className="box"
19
  data-expanded={expanded}
20
/>
21

22

More about the layout prop

We just saw that setting the layout prop to true gives us the ability to animate a component between layouts by transitioning any properties related to its size or position. I recently discovered that there are more values that the layout prop can take:

• layout="position": we only smoothly transition the position-related properties. Size-related properties will transition abruptly.
• layout="size": we only smoothly transition the size-related properties. Position-related properties will transition abruptly.

To illustrate this, I built the widget below that showcases how the transition of a motion component is altered based on the value of the layout prop:

Why would we need to use these other layout properties? What's the practical use? you may ask. Sometimes, as a result of a layout animation, the content of a component that resizes can end up "squished" or "stretched". If you see this happening when working on a layout animation, chances are that it can be fixed by simply setting the layout prop to position.

Below you'll find an example of such a use case:

• Removing items in this horizontal list will affect the size of each component. By default, you will notice the components getting slightly squished when an item is removed.
• Wrapping the content in a motion component and setting layout to position by toggling the switch will fix all the distortions you may observe on the content of the motion block. Each component will resize gracefully with a more natural transition.

1
<motion.div layout>
2
  <Label variant="success">
3
    <div
4
      style={{ 
5
        width: '100%',
6
        display: 'flex',
7
        justifyContent: 'start',
8
      }}
9
    >
10
      <DismissButton/>
11
      <span>{text}</span>
12
    </div>
13
  </Label>
14
</motion.div>

Shared layout animations and LayoutGroup

These two concepts are perhaps what I struggled the most with recently as:

• they appear to be closely related based on their names but have very distinct purposes and use cases
• there has been a lot of API changes in this area. Thus, everything I thought I had mastered was actually brand new and a bit different 😅

And I know I'm not the only one, I've seen many people confusing shared layout animations and LayoutGroup

Shared layout animations

One might think that this is yet another type of layout animation like we saw in the previous part, but with a twist. It's not wrong, but also not quite exact either.

Shared layout animations have their own API, not directly related to the layout prop. Instead of animating a component's position and size, we are animating a component between all its instances that have a common layoutId prop. To illustrate this concept let's look at the playground below:

import { motion } from 'framer-motion';
import React from 'react';
import { List, Item, ArrowIcon } from './Components';
import './scene.css';

const ITEMS = [1, 2, 3];

const SelectableList = () => {
  const [selected, setSelected] = React.useState(1);

  return (
    <List>
      {ITEMS.map(item => (
        <Item 
          onClick={() => setSelected(item)}  
          onKeyDown={(event: { key: string }) => event.key === 'Enter' ? setSelected(item) : null} 
          tabIndex={0}
        >
          
          <div>Item {item}</div>
          {item === selected ? 
            <motion.div layoutId="arrow">
               <ArrowIcon
                style={{
                  height: '24px',
                  color: '#5686F5',
                  transform: 'rotate(-90deg)',
                }}
               />
            </motion.div> : null
          }
        </Item>
      ))}
    </List>
  )
}

export default SelectableList

We can see in this example that:

• We're transitioning between multiple instances of the Arrow component
• They all share a common layoutId which tells Framer Motion that these components are related and need to transition from one instance to the newly "active" one when the user clicks on a new item.

The shared aspect comes from the effect of the component moving from one position to another as if it was the same. And that's what I love about shared layout animations. It's all smoke and mirrors. Like a magic trick 🪄!

The "magic" behind it is actually quite simple:

1. In our example above, when clicking on a new element, the Arrow component that was displayed on the screen fades away to reveal a new instance of the Arrow component
2. That new Arrow component is the one that will be eventually positioned under our newly selected element on the list
3. That component then transitions to its final position

To show you this effect, I reused the demo above and gave a different color to each instance of Arrow so you can better visualize what's happening:

One component I like to decorate with shared layout animations is Tabs. We can leverage this type of animation to add proper transitions for the "selected indicator" but also to a "hover highlight" like Vercel does on their own Tabs component! Below is an example implementation of such component with these two layout animations:

• We can see the "selected indicator" transitioning from one tab to another when a new one is selected
• The "hover highlight" will follow the user's mouse when hovering over the Tabs component
• Each shared layout animation has a distinct layoutId prop: underline and highlight

import { motion } from 'framer-motion';
import React from 'react';
import { Wrapper, Tab } from './Components';
import './scene.css';

const Tabs = () => {
  const [focused, setFocused] = React.useState(null);
  const [selected, setSelected] = React.useState('Item 1');
  const tabs = ['Item 1', 'Item 2', 'Item 3'];

  return (
    <Wrapper onMouseLeave={() => setFocused(null)}>
      {tabs.map((item) => (
        <Tab
          key={item}
          onClick={() => setSelected(item)}
          onKeyDown={(event: { key: string }) =>
            event.key === 'Enter' ? setSelected(item) : null
          }
          onFocus={() => setFocused(item)}
          onMouseEnter={() => setFocused(item)}
          tabIndex={0}
        >
          <span>{item}</span>
          {focused === item ? (
            <motion.div
              transition={{
                layout: {
                  duration: 0.2,
                  ease: 'easeOut',
                },
              }}
              style={{
                position: 'absolute',
                bottom: '-2px',
                left: '-10px',
                right: 0,
                width: '140%',
                height: '110%',
                background: '#23272F',
                borderRadius: '8px',
                zIndex: 0,
              }}
              layoutId="highlight"
            />
          ) : null}
          {selected === item ? (
            <motion.div
              style={{
                position: 'absolute',
                bottom: '-10px',
                left: '0px',
                right: 0,
                height: '4px',
                background: '#5686F5',
                borderRadius: '8px',
                zIndex: 0,
              }}
              layoutId="underline"
            />
          ) : null}
        </Tab>
      ))}
    </Wrapper>
  );
}

export default Tabs;

There's however one little problem. What if we wanted to build a reusable component that has a shared layout animation defined and use it twice within the same page? Well, both seemingly distinct shared layout animation would end up with the same layoutId prop which, as a result, would cause things to get a bit weird:

This is where LayoutGroup comes into the picture 👀.

LayoutGroup: the namespacing use case

For this use case, we can see LayoutGroup as a tool to use on top of shared layout animations and not directly related to them as it may have first seemed.

We saw above that layoutId props do not take into consideration which instance of a component they are used in, i.e. they are global. In this first use case, we'll use it to namespace our shared layout animations: give them a unique id so they can be rendered multiple times and still behave distinctly.

1
const ComponentsWithSharedLayoutAnimation = () => {
2
  //...
3

4
  return (
5
    //...
6
    <motion.div layoutId="shared-layout-animation" />
7
    //...
8
  );
9
};
10

11
const App = () => (
12
  <>
13
    <LayoutGroup id="1">
14
      <ComponentsWithSharedLayoutAnimation />
15
    </LayoutGroup>
16
    <LayoutGroup id="2">
17
      <ComponentsWithSharedLayoutAnimation />
18
    </LayoutGroup>
19
  </>
20
);

By using LayoutGroup in our Tabs component implementation, we can now make it a truly reusable component and work around the bug we showcased in the previous part: the shared layout animations are now only "shared" within their own LayoutGroup.

1
const Tabs = ({ id }) => {
2
  const [focused, setFocused]
3
    = React.useState(null);
4
  const [selected, setSelected]
5
    = React.useState('Item 1');
6
  const tabs = [
7
    'Item 1', 
8
    'Item 2', 
9
    'Item 3'
10
  ];
11

12
  return (
13
    <LayoutGroup id={id}>
14
      <Wrapper
15
        onMouseLeave={() => 
16
          setFocused(null)
17
        }
18
      >
19
        {tabs.map((item) => (
20
          <Tab {/*...*/}>
21
  {/* Tab implementation... */}
22
          </Tab>
23
        )}
24
      </Wrapper>
25
    </LayoutGroup>
26
  );

LayoutGroup: the grouping use case

Namespacing shared layout animations is not the only use case for LayoutGroup. Its original purpose is actually to:

Group motion components that should perform layout animations together.

But what does that exactly mean?

We saw in the first part that a layout animation will transition a component from one layout to another when a rerender occurs. That works fantastically well for everything within the motion component with the layout prop, but what about the sibling components?

As a result of one component's layout animation, the overall layout of the page may be affected. For example when removing an item from a list, all the surrounding components will need to adapt through a transition or a resize. The problem here is that there's no way to make those other components transition smoothly as is because:

• they are not necessarily motion components themselves
• they are not rerendering since not interacted with
• since they are not rerendering they are unable to perform a layout animation by themselves, even if defined.

This can be fixed by wrapping each sibling components in a motion component with the layout set to true (if the siblings were not motion components themselves already), and wrapping all the components we wish to perform a smooth transition when the overall layout changes in a LayoutGroup.

In the little widget below I showcase this by rendering two instances of a list component where each item is a motion component:

1
<>
2
  <List
3
    items={[...]}
4
    name="List 1"
5
  />
6
  <List
7
    items={[...]}
8
    name="List 2"
9
  />
10
</>

• Try to remove an item from the first list and notice that the items within the first list perform a smooth layout animation and that the second list, however, moves abruptly
• Toggle LayoutGroup wrapping on and notice that now when removing an item from the first list, the second list transition smoothly to its target position.

Reorder

Drag-to-reorder items in a list where each item then smoothly moves to its final position is perhaps the best in class use case when it comes to layout animations. It's actually the first use case I thought about when I discovered layout animations in the first place a year ago.

Lucky us, the developers at Framer gave us a ready-to-use set of components to handle that specific use case with ease 🎉. They provided 2 components that we're going to use in follow-up examples:

1. Reorder.Group where we pass our list of items, the direction of the reorder (horizontal or vertical), and the onReorder callback which will return the latest order of the list
2. Reorder.Item where we pass the value of an item in the list

1
const MyList = () => {
2
  const [items, setItems] = React.useState(['Item 1', 'Item 2', 'Item 3']);
3

4
  return (
5
    <Reorder.Group
6
      // Specify the direction of the list (x for horizontal, y for vertical)
7
      axis="y"
8
      // Specify the full set of items within your reorder group
9
      values={items}
10
      // Callback that passes the newly reordered list of item
11
      // Note: simply passing a useState setter here is equivalent to
12
      // doing `(reordereditems) => setItmes(reordereditems)`
13
      onReorder={setItems}
14
    >
15
      {items.map((item) => (
16
        // /!\ don't forget the value prop!
17
        <Reorder.Item key={item} value={item}>
18
          {item}
19
        </Reorder.Item>
20
      ))}
21
    </Reorder.Group>
22
  );
23
};

With just a few lines of code, we can get a ready-to-use list with a drag-to-reorder effect! And that's not all of it:

• Each Reorder.Item is a motion component
• Each Reorder.Item component in the list is able, out-of-the-box, to perform layout animations

Thus it's very easy to add a lot more animations on top of this component to build a truly delightful user experience. There are, however, two little catches that I only discovered when I started working with the Reorder components 👇

Combining everything

In the playground below, you will find a more advanced example that leverages Reorder.Group and Reorder.Item along with some other aspects of layout animations that we saw earlier:

• layout="position" is used on the content of each item to avoid distortions when they are selected and a layout animation is performed
• Custom React styled-components use Reorder components through polymorphism

1
//...
2

3
<Card
4
  as={Reorder.Item}
5
  //...
6
  value={item}
7
>
8
  <Card.Body as={motion.div} layout="position">
9
    <Checkbox
10
      id={`checkbox-${item.id}`}
11
      aria-label="Mark as done"
12
      checked={item.checked}
13
      onChange={() => completeItem(item.id)}
14
    />
15
    <Text>{item.text}</Text>
16
  </Card.Body>
17
</Card>
18

19
//...

• Inline styles are used for the borderRadius of the item to avoid distortions when the item resizes
• position: relative has been added as inline style to the Reorder.Item to fix overlap issues that occur while dragging elements of the list over one another
• AnimatePresence is used to allow for exit animations when elements are removed from the list

1
//...
2
<AnimatePresence>
3
  {items.map((item) => (
4
    <motion.div
5
       exit={{ opacity: 0, transition: { duration: 0.2 } }}
6
    />
7
      <Card
8
        as={Reorder.Item}
9
        style={{
10
          position: 'relative', // this is needed to avoid weird overlap
11
          borderRadius: '12px', // this is set as inline styles to avoid distortions
12
          width: item.checked ? '70%' : '100%', // will be animated through layout animation
13
        }}
14
        value={item}
15
      >
16
        //...
17
      </Card>
18
    </motion.div>
19
    //...
20
  )}
21
</AnimatePresence>
22
//...

• The list and its sibling elements are wrapped in a LayoutGroup to perform smooth layout animations when the task list updates and changes the overall layout

1
<LayoutGroup>
2
  <Reorder.Group axis="y" values={items} onReorder={setItems}>
3
    <AnimatePresence>
4
      {//...}
5
    </AnimatePresence>
6
  </Reorder.Group>
7
  <motion.div layout>
8
    <hr />
9
    <span>Check items off the list when you&apos;re done!</span>
10
  </motion.div>
11
</LayoutGroup>

Want to run this example yourself and hack on top of it? You can find the full implementation of this example on my blog's Github repository.

Conclusion

You now know pretty much everything there is to know about Framer Motion layout animations 🎉. Whether it's for some basic use cases, such as the Notification List we've seen in the first part, adding little details like the shared layout animations from the tabs components, to building reorderable lists with complex transitions: layout animations have no more secrets to you.

I hope this blog post can serve you as a guide/helper to make your own animations look absolutely perfect ✨, especially when working on the nitty-gritty details of your transitions. It may sound overkill to spend so much time reading and working around the issues we showcased in this blog post, but trust me, it's worth it!

Want to go further?

I'd suggest taking a look at some of the complex examples provided in the Framer Motion documentation. The team came up with very good examples such as this drag to reorder tabs component which contains every concept used in the task list example that I introduced in this blog post. After that, I'd try to see where you could sprinkle some layout animation magic on your own projects 🪄. There's no better way of learning than building things by yourself!