A poser is used to animate an element and its poser children.

Note: For React, use posed components.


import pose from 'popmotion-pose'



Posers are created with the pose function.

pose accepts two arguments: A HTML or SVG element, and an object of pose config.

const poser = pose(element, config)


Animating to a pose defined in the pose config is a matter of calling the poser’s set method:



set returns a Promise, which resolves once all animations, and animations of any child posers, are complete.

// Promise
poser.set('nameOfPose').then(() => /* Do other thing */)

// Async
await poser.set('nameOfPose')
/* Do other thing */

Multiple animations

When a pose is set on a poser, it is only set on the values defined in that pose. Which means, if we have two poses with different sets of properties, we can animate both at the same time:

const poser = pose(element, {
  flash: {
    backgroundColor: '#f00',
    transition: ({ from, to }) => tween({ from, to, yoyo: Infinity })
  shake: {
    x: true, // We're not using `to` in the transition but want to animate x
    transition: ({ from, velocity }) => spring({
      from, velocity,
      stiffness: 1000,
      damping: 100



By default, Pose will choose a transition depending on the property being animated:

Note: In a future release, these default animations will be configurable via personality settings.

Custom transitions

Every pose has an optional transition property that allows you to define a custom transition:

const config = {
  attention: {
    scale: 1.2,
    transition: ({ from, to }) => tween({ from, to, yoyo: Infinity })
  rest: { scale: 1 }

This function is run once for each animating property and must return a Popmotion animation (or false for no animation).

The transition function receives a single argument, an object containing:

  • Information about the current transition: from, to, velocity, key and prevPoseKey properties.
  • Transition props. These can be set statefully as config.props or via the setProps method. Or they can be set temporarily, as the second argument provided to set.
  • React Pose: All props set on the posed component.

You can use these props to create different animations for different values.

Dynamic values

Values on a pose can be set as a function that returns the to property for a transition.

This function is passed all the same properties as the transition function except for to, which this function is responsible for returning.

const config = {
  open: { x: 0 },
  closed: {
    x: ({ i }) => Math.sin(i * 0.5) * 100

// Vanilla
// --------------------
itemPosers = items.map((item, i) => pose(item, {
  props: { i }

// React
// --------------------
const Item = posed.li(config)

// In component render
{items.map((item, i) => <Item pose="closed" i={i} />}


Any element can be made draggable by passing the draggable property to config:

const config = { draggable: true };

Dragging can be locked to a single axis by passing the name of that axis instead:

const config = { draggable: 'x' };

dragEnd pose

When an element is draggable and a user stops dragging, a special pose called dragEnd is automatically set.

You can decide what animation fires by using the transition property:

const config = {
  draggable: 'x',
  dragEnd: {
    transition: ({ from }) => // return custom animation

Drag lifecycle events

onDragStart and onDragEnd functions can be defined to fire when a user starts and stops dragging:

const config {
  draggable: true,
  onDragStart: (e) => // not our business!

Bound drag movement

We can limit pointer-driven movement with the dragBounds object.

It can restrict movement in both dimensions with optional left, right, top, and bottom properties:

const config = {
  draggable: 'x',
  dragBounds: { left: 0, right: 500 }

onChange events

We can append onChange callbacks to any value with the onChange map:

const config = {
  draggable: true,
  onChange: {
    x: v => // Do your thing!


With a poser’s addChild method, we can spawn a new poser as a child.

When we call set on the parent poser, the same set will be passed down to its children. Like this, we can orchestrate multiple animations with a single call.

Add children

addChild is called exactly like pose:

const childPoser = parentPoser.addChild(element, childConfig)

Now, all set calls on parentPoser will be passed down to all of its children. It doesn’t even need a pose with that label of its own to do so.


We can still call set on the child posers without affecting the parent or its siblings:


Delay and stagger children

We can delay the propagation of a set call delayChildren on the parent pose:

const parentConfig = {
  initialPose: 'close',
  open: {
    x: '0%',
    delayChildren: 200
  close: { x: '100%' }

Or if we wanted to stagger over the children, we can do so with staggerChildren, and optionally staggerDirection:

const sidebarConfig = {
  initialPose: 'close',
  open: {
    x: '0%',
    delayChildren: 200,
    staggerChildren: 50,
    staggerDirection: -1 // stagger from the last child
  close: { x: '100%' }

Passive values

Not all values have to be actively animated via a pose. The passive property can be used to define values that simply subscribe to actively animated values and update when they do.

For instance, we could update y when x updates like so:

const config = {
  draggable: 'x',
  passive: {
    y: ['x', x => x]

Each passive value is defined as a tuple:

[subscribeKey: string, transform: v => v, fromParent?: boolean]
  • subscribeKey: The key of the value we’ll subscribe to.
  • transform: Receives the latest subscribed value and returns the passive value.
  • fromParent: If true, will subscribe to this value in the direct parent instead of the current poser.


Animating positional and dimensional properties like width and top is tasking for browsers and can cause stuttering in animations.

The FLIP technique was developed to animate these performantly by replacing them with transforms.

When animating these properties, flip: true can be set to use FLIP:

// Pose will automatically measure the difference
// in element size and animate `scaleX` instead:
const config = {
  open: { width: 200, flip: true }, // Will FLIP
  closed: { width: 0 } // Will not FLIP

Explicit FLIP methods

Alternatively, we might want to transition to a new state where we don’t know the new position or size.

For instance, if we change the children of the element, we might change the height. We can smoothly transition to the new height with the measure and flip methods:

const poser = pose(element, config)

// Measure the current bounding box

// Do stuff, like swap the element's children

// FLIP!

Alternatively, we can just pass a callback to flip:




set(poseName: string, props?: Object): Promise

Sets the current pose to poseName. If Poser has children, this will get set on those, too. Returns a Promise.

If props is defined, these will be passed through to the selected pose’s transition function.


setProps(props: Object)

Sets props on the poser that will be passed to any functions set on a pose.



Measures the current bounding box. Use this before making a change to the element that will affect physical dimensions (like adding new children, or moving it in the DOM), and then use flip to animate it to the new size.



Performs a FLIP animation between the previously measured bounding box and the latest one.

You can add flip as a custom pose use a custom transition for this:

const config = {
  flip: {
    transition: () => // your custom transition


addChild(element: HTMLElement | SVGElement, config: PoseConfig): Poser

Creates and returns a new Poser as a child.


removeChild(poser: Poser)

Removes a child.



Removes all child posers and destroys them.



Stops all active transitions of this Poser and its children.