Animation Upgrade Guide

• Introduction
• States
• Animate
• Animation
• Undocumented

Introduction

The most important part when upgrading an existing project to the new Framer Library is one breaking change that is introduced in the updated API. Namely that layer.states.current now returns a State object instead of a string. The name of the current state is still available through layer.states.current.name.

# Before
layer.states.current

# After
layer.states.current.name

The rest of the documented API is fully backwards compatible, but shows a console log warning when you try to use it. There also were some undocumented features that have been removed in favor of the new API.

States

The state properties weren't exposed before. Now they are through the layer.states object.

Adding

Adding a single state.

# Before
layer.states.add "stateA",
  x: 100

# After
layer.states.stateA =
  x: 100

Adding multiple states.

# Before
layer.states.add
  stateA:
    x: 100
  stateB:
    y: 200

# After
layer.states =
  stateA:
    x: 100
  stateB:
    y: 200

Removing

Used to be a function, but now uses JavaScript's delete operator.

# Before
layer.states.remove "stateA"

# After
delete layer.states.stateA

Switching

Used to be a function on layer.states and is now a function on layer. There used to be animations by default, but this now happens instantly. You can use the layer's animate function to switch with an animation.

Switch with an animation.

# Before
layer.states.switch "stateA"

# After
layer.animate "stateA"

Switch without an animation.

# Before
layer.states.switchInstant "stateA"

# After
layer.stateSwitch "stateA"

Cycling

Allows you to easily cycle through the layer's states. This was previously achieved with layer.states.next().

Through all states.

# Before
layer.states.next()

# After
layer.stateCycle()

Through specific states.

# Before
layer.states.next("stateA", "stateB")

# After
layer.stateCycle("stateA", "stateB")

Animation options

The layer.states.animationOptions object used to only influence state animations, but is now a property on layer and influences all animations on a layer.

# Before
layer.states.animationOptions = 
  time: 0.5

# After
layer.animationOptions =
  time: 0.5

You can now also add specific animation options to a state. They will influence the animation towards the state.

layer.states.stateA = 
  x: 100
  animationOptions:
    time: 0.5

Events

Normal notation: Before switching states.

# Before
layer.on Events.StateWillSwitch, ->
  print "state switch started"

# After
layer.on Events.StateSwitchStart, ->
  print "state switch started"

Normal notation: After switching states.

# Before
layer.on Events.StateDidSwitch, ->
  print "switch ended"

# After
layer.on Events.StateSwitchEnd, ->
  print "switch ended"

Normal notation: When state switching animation stopped.

# Before
## Not available

# After
layer.on Events.StateSwitchStop, ->
  print "switch animation stopped"

Shortcut: Before switching states.

# Before
layer.onStateWillSwitch ->
  print "state switch started"

# After
layer.onStateSwitchStart ->
  print "state switch started"

Shortcut: After switching states.

# Before
layer.onStateDidSwitch ->
  print "switch ended"

# After
layer.onStateSwitchEnd ->
  print "switch ended"

Shortcut: When state switching animation stopped.

# Before
## Not available

# After
layer.onStateSwitchStop ->
  print "switch animation stopped"

Animate

Properties

The animation object has changed and so has animate. You can now set properties directly on the animation instead of using the properties keyword.

# Before
layer.animate
  properties:
    x: 100

# After
layer.animate
  x: 100

States

Instead of animating between states by using switch you can now use the animate function on a layer.

# Before
layer.states.switch "a"

# After
layer.animate "a"

Animation options

Every function that starts an animation takes an animation options object as last argument.

# After
layerA.animate 
  x: 100
  options:
    curve: "spring"

layerA.animate "a",
  options:
    curve: "spring"

layerA.stateCycle "a", "b",
  options:
    curve: "spring"

For animating properties, you can also add an options key.

# After
layerA.animate 
  x: 100
  options:
    curve: "spring"

Animation

Layer has become a required parameter of the Animation object's constructor. The properties have also moved to the top level of the Animation object instead of the properties key. Because of this the animation options have moved to the options key.

# Before
animation = new Animation
  time: 0.5
  layer: layerA 
  properties:
    x: 100

# After
animation = new Animation layerA,
  x: 100
  options:
    time: 0.5

Undocumented

You might have been using some of these undocumented features. They have been removed in favour of the new API.

layer.states.previous

Used to return the name of the previous state and now returns the state object. Easily get the name by calling the name property.

# Before
layer.states.previous
# After
layer.states.previous.name

layer.states.on

Use event handlers on layer instead of states. See the Events section for the updated event names.

# Before
layer.states.on Events.StateDidSwitch, ->
  print "state switch ended"
# After
layer.on Events.StateSwitchEnd, ->
  print "state switch ended"

layer.states.state

Returned the state name. This can now be done by calling name on states.

# Before
layer.states.state

# After
layer.states.current.name

layer.states.stateNames

Became a property on layer.

# Before
layer.states.stateNames
layer.states.all
layer.states.states

# After
layer.stateNames

layer.states.last()

The last method is no longer required as you can now easily animate to the previous state using the animate function.

# Before
layer.states.last()

# After
layer.animate "previous"

layer.states.animatingKeys()

Wasn't documented and used much, and will be removed.

# Before
layer.states.animatingKeys()

# After
# Removed.