motion animator objc

A Motion Animator creates performant, interruptible iOS animations from motion specs.

Objective-C

An animator for iOS 9+ that combines the best aspects of modern UIView and CALayer animation APIs.

🎉	Implicit and explicit additive animations.
🎉	Parameterized motion with the Interchange.
🎉	Provide velocity to animations directly from gesture recognizers.
🎉	Maximize frame rates by relying more on Core Animation.
🎉	Animatable properties are Swift enum types.
🎉	Consistent model layer value expectations.

The following properties can be implicitly animated using the MotionAnimator on iOS 9 and up:

CALayer `anchorPoint`
CALayer `backgroundColor`	UIView `backgroundColor`
CALayer `bounds`	UIView `bounds`
CALayer `borderWidth`
CALayer `borderColor`
CALayer `cornerRadius`
CALayer `height`	UIView `height`
CALayer `opacity`	UIView `alpha`
CALayer `position`	UIView `center`
CALayer `rotation`	UIView `rotation`
CALayer `scale`	UIView `scale`
CALayer `shadowColor`
CALayer `shadowOffset`
CALayer `shadowOpacity`
CALayer `shadowRadius`
CALayer `transform`	UIView `transform`
CALayer `width`	UIView `width`
CALayer `x`	UIView `x`
CALayer `y`	UIView `y`
CALayer `z`
CAShapeLayer `strokeStart`
CAShapeLayer `strokeEnd`

Note: any animatable property can also be animated with MotionAnimator’s explicit animation APIs, even if it’s not listed in the table above.

Is a property missing from this list? We welcome pull requests!

MotionAnimator: a drop-in replacement

UIView’s implicit animation APIs are also available on the MotionAnimator:

// Animating implicitly with UIView APIs
UIView.animate(withDuration: 1.0, animations: {
  view.alpha = 0.5
})

// Equivalent MotionAnimator API
MotionAnimator.animate(withDuration: 1.0, animations: {
  view.alpha = 0.5
})

But the MotionAnimator allows you to animate more properties — and on more iOS versions:

UIView.animate(withDuration: 1.0, animations: {
  view.layer.cornerRadius = 10 // Only works on iOS 11 and up
})

MotionAnimator.animate(withDuration: 1.0, animations: {
  view.layer.cornerRadius = 10 // Works on iOS 9 and up
})

MotionAnimator makes use of the MotionInterchange, a standardized format for representing animation traits. This makes it possible to tweak the traits of an animation without rewriting the code that ultimately creates the animation, useful for building tweaking tools and making motion “stylesheets”.

// Want to change a trait of your animation? You'll need to use a different function altogether
// to do so:
UIView.animate(withDuration: 1.0, animations: {
  view.alpha = 0.5
})
UIView.animate(withDuration: 1.0, delay: 0.5, options: [], animations: {
  view.alpha = 0.5
}, completion: nil)

// But with the MotionInterchange, you can create and manipulate the traits of an animation
// separately from its execution.
let traits = MDMAnimationTraits(duration: 1.0)
traits.delay = 0.5

let animator = MotionAnimator()
animator.animate(with: traits, animations: {
  view.alpha = 0.5
})

The MotionAnimator can also be used to replace explicit Core Animation code with additive explicit animations:

let from = 0
let to = 10
// Animating expicitly with Core Animation APIs
let animation = CABasicAnimation(keyPath: "cornerRadius")
animation.fromValue = (from - to)
animation.toValue = 0
animation.isAdditive = true
animation.duration = 1.0
view.layer.add(animation, forKey: animation.keyPath)
view.layer.cornerRadius = to

// Equivalent implicit MotionAnimator API. cornerRadius will be animated additively by default.
view.layer.cornerRadius = 0
MotionAnimator.animate(withDuration: 1, animations: {
  view.layer.cornerRadius = 10
})

// Equivalent explicit MotionAnimator API
// Note that this API will also set the final animation value to the layer's model layer, similar
// to how implicit animations work, and unlike the explicit pure Core Animation implementation
// above.
let animator = MotionAnimator()
animator.animate(with: MDMAnimationTraits(duration: 1.0),
                 between: [0, 10],
                 layer: view.layer,
                 keyPath: .cornerRadius)

Springs on iOS require an initial velocity that’s normalized by the displacement of the animation. MotionAnimator calculates this for you so that you can directly provide gesture recognizer velocity values:

// Common variables
let gestureYVelocity = gestureRecognizer.velocity(in: someContainerView).y
let destinationY = 75

// Animating springs implicitly with UIView APIs
let displacement = destinationY - view.position.y
UIView.animate(withDuration: 1.0,
               delay: 0,
               usingSpringWithDamping: 1.0,
               initialSpringVelocity: gestureYVelocity / displacement,
               options: [],
               animations: {
                 view.layer.position = CGPoint(x: view.position.x, y: destinationY)
               },
               completion: nil)

// Equivalent MotionAnimator API
let animator = MotionAnimator()
let traits = MDMAnimationTraits(duration: 1.0)
traits.timingCurve = MDMSpringTimingCurveGenerator(duration: traits.duration,
                                                   dampingRatio: 1.0,
                                                   initialVelocity: gestureYVelocity)
animator.animate(with: traits,
                 between: [view.layer.position.y, destinationY],
                 layer: view.layer,
                 keyPath: .y)

API snippets

Implicit animations

MotionAnimator.animate(withDuration: <#T##TimeInterval#>) {
  <#code#>
}

MotionAnimator.animate(withDuration: <#T##TimeInterval#>,
                       delay: <#T##TimeInterval#>,
                       options: <#T##UIViewAnimationOptions#>,
                       animations: {
  <#code#>
})

Explicit animations

let traits = MDMAnimationTraits(delay: <#T##TimeInterval#>,
                                duration: <#T##TimeInterval#>,
                                animationCurve: <#T##UIViewAnimationCurve#>)
let animator = MotionAnimator()
animator.animate(with: <#T##MDMAnimationTraits#>,
                 between: [<#T##[From (Any)]#>, <#T##[To (Any)]#>],
                 layer: <#T##CALayer#>,
                 keyPath: <#T##AnimatableKeyPath#>)

Animating transitions

let animator = MotionAnimator()
animator.shouldReverseValues = transition.direction == .backwards

let traits = MDMAnimationTraits(delay: <#T##TimeInterval#>,
                                duration: <#T##TimeInterval#>,
                                animationCurve: <#T##UIViewAnimationCurve#>)
animator.animate(with: <#T##MDMAnimationTraits#>,
                 between: [<#T##[From (Any)]#>, <#T##[To (Any)]#>],
                 layer: <#T##CALayer#>,
                 keyPath: <#T##AnimatableKeyPath#>)

Creating motion specifications

class MotionSpec {
  static let chipWidth = MDMAnimationTraits(delay: 0.000, duration: 0.350)
  static let chipHeight = MDMAnimationTraits(delay: 0.000, duration: 0.500)
}

let animator = MotionAnimator()
animator.shouldReverseValues = transition.direction == .backwards

animator.animate(with: MotionSpec.chipWidth,
                 between: [<#T##[From (Any)]#>, <#T##[To (Any)]#>],
                 layer: <#T##CALayer#>,
                 keyPath: <#T##AnimatableKeyPath#>)
animator.animate(with: MotionSpec.chipHeight,
                 between: [<#T##[From (Any)]#>, <#T##[To (Any)]#>],
                 layer: <#T##CALayer#>,
                 keyPath: <#T##AnimatableKeyPath#>)

Animating from the current state

// Will animate any non-additive animations from their current presentation layer value
animator.beginFromCurrentState = true

Debugging animations

animator.addCoreAnimationTracer { layer, animation in
  print(animation.debugDescription)
}

Stopping animations in reaction to a gesture recognizer

if gesture.state == .began {
  animator.stopAllAnimations()
}

Removing all animations

animator.removeAllAnimations()

Main thread animations vs Core Animation

Animation systems on iOS can be split into two general categories: main thread-based and Core Animation.

Main thread-based animation systems include UIDynamics, Facebook’s POP, or anything driven by a CADisplayLink. These animation systems share CPU time with your app’s main thread, meaning they’re sharing resources with UIKit, text rendering, and any other main-thread bound processes. This also means the animations are subject to main thread jank, in other words: dropped frames of animation or “stuttering”.

Core Animation makes use of the render server, an operating system-wide process for animations on iOS. This independence from an app’s process allows the render server to avoid main thread jank altogether.

The primary benefit of main thread animations over Core Animation is that Core Animation’s list of animatable properties is small and unchangeable, while main thread animations can animate anything in your application. A good example of this is using POP to animate a “time” property, and to map that time to the hands of a clock. This type of behavior cannot be implemented in Core Animation without moving code out of the render server and in to the main thread.

The primary benefit of Core Animation over main thread animations, on the other hand, is that your animations will be much less likely to drop frames simply because your app is busy on its main thread.

When evaluating whether to use a main thread-based animation system or not, check first whether the same animations can be performed in Core Animation instead. If they can, you may be able to offload the animations from your app’s main thread by using Core Animation, saving you valuable processing time for other main thread-bound operations.

MotionAnimator is a purely Core Animation-based animator. If you are looking for main thread solutions then check out the following technologies:

Core Animation: a deep dive

Recommended reading:

Building Animation Driven Interfaces

Core Animation in Practice, Part 1

Core Animation in Practice, Part 2

Building Interruptible and Responsive Interactions

Advanced Graphics and Animations for iOS Apps

Advances in UIKit Animations and Transitions

Animating Layer Content

Advanced Animation Tricks

Additive animations: animateWithDuration in iOS 8

There are two primary ways to animate with Core Animation on iOS:

implicitly, with the UIView animateWithDuration: APIs, or by setting properties on standalone CALayer instances (those that are not backing a UIView), and
explicitly, with the CALayer addAnimation:forKey: APIs.

A subset of UIView’s and CALayer’s public APIs is animatable by Core Animation. Of these animatable properties, some are implicitly animatable while some are not. Whether a property is animatable or not depends on the context within which it’s being animated, and whether an animation is additive or not depends on which animation API is being used. With this matrix of conditions it’s understandable that it can sometimes be difficult to know how to effectively make use of Core Animation.

The following quiz helps illustrate that the UIKit and Core Animation APIs can often lead to unintuitive behavior. Try to guess which of the following snippets will generate an animation and, if they do, what the generated animation’s duration will be:

Imagine that each code snippet is a standalone unit test (because they are!).

let view = UIView()
UIView.animate(withDuration: 0.8, animations: {
  view.alpha = 0.5
})

Click to see the answer

Generates an animation with duration of 0.8.

let view = UIView()
UIView.animate(withDuration: 0.8, animations: {
  view.layer.opacity = 0.5
})

Click to see the answer

Generates an animation with duration of 0.8.

let view = UIView()
UIView.animate(withDuration: 0.8, animations: {
  view.layer.cornerRadius = 3
})

Click to see the answer

On iOS 11 and up, generates an animation with duration of 0.8. Older operating systems will not generate an animation.

let view = UIView()
view.alpha = 0.5

Click to see the answer

Does not generate an animation.

let view = UIView()
view.layer.opacity = 0.5

Click to see the answer

Does not generate an animation.

let layer = CALayer()
layer.opacity = 0.5

Click to see the answer

Does not generate an animation.

let view = UIView()
window.addSubview(view)
let layer = CALayer()
view.layer.addSublayer(layer)

// Pump the run loop once.
RunLoop.main.run(mode: .defaultRunLoopMode, before: .distantFuture)

layer.opacity = 0.5

Click to see the answer

Generates an animation with duration of 0.25.

let view = UIView()
window.addSubview(view)
let layer = CALayer()
view.layer.addSublayer(layer)

// Pump the run loop once.
RunLoop.main.run(mode: .defaultRunLoopMode, before: .distantFuture)

UIView.animate(withDuration: 0.8, animations: {
  layer.opacity = 0.5
})

Click to see the answer

Generates an animation with duration of 0.25. This isn't a typo: standalone layers read from the current CATransaction rather than UIView's parameters when implicitly animating, even when the change happens within a UIView animation block.

What properties can be explicitly animated?

For a full list of animatable CALayer properties, see the Apple documentation.

MotionAnimator’s explicit APIs can be used to animate any property that is animatable by Core Animation.

What properties can be implicitly animated?

UIKit and Core Animation have different rules about when and how a property can be implicitly animated.

UIView properties generate implicit animations only when they are changed within an animateWithDuration: animation block.

CALayer properties generate implicit animations only when they are changed under either of the following conditions:

if the CALayer is backing a UIView, the CALayer property is a supported implicitly animatable property (this is not documented anywhere), and the property is changed within an animateWithDuration: block, or
if: the CALayer is not backing a UIView (an “unhosted layer”), the layer has been around for at least one CATransaction flush — either by invoking CATransaction.flush() or by letting the run loop pump at least once — and the property is changed at all.

This behavior can be somewhat difficult to reason through, most notably when trying to animate CALayer properties using the UIView animateWithDuration: APIs. For example, CALayer’s cornerRadius was not animatable using animateWithDuration: up until iOS 11, and many other CALayer properties are still not implicitly animatable.

// This doesn't work until iOS 11.
UIView.animate(withDuration: 0.8, animations: {
  view.layer.borderWidth = 10
}, completion: nil)

// This works back to iOS 9.
MotionAnimator.animate(withDuration: 0.8, animations: {
  view.layer.borderWidth = 10
}, completion: nil)

The MotionAnimator provides a more consistent implicit animation API with a well-defined set of supported properties.

In general, when will changing a property cause an implicit animation?

The following charts describe when changing a property on a given object will cause an implicit animation to be generated.

UIView

let view = UIView()

// inside animation block
UIView.animate(withDuration: 0.8, animations: {
  view.alpha = 0.5 // Will generate an animation with a duration of 0.8
})

// outside animation block
view.alpha = 0.5 // Will not animate

// inside MotionAnimator animation block
MotionAnimator.animate(withDuration: 0.8, animations: {
  view.alpha = 0.5 // Will generate an animation with a duration of 0.8
})

UIVIew key path	inside animation block	inside MotionAnimator animation block
`alpha`	✓	✓
`backgroundColor`	✓	✓
`bounds`	✓	✓
`bounds.size.height`	✓	✓
`bounds.size.width`	✓	✓
`center`	✓	✓
`center.x`	✓	✓
`center.y`	✓	✓
`transform`	✓	✓
`transform.rotation.z`	✓	✓
`transform.scale`	✓	✓

Backing CALayer

Every UIView has a backing CALayer.

let view = UIView()

// inside animation block
UIView.animate(withDuration: 0.8, animations: {
  view.layer.opacity = 0.5 // Will generate an animation with a duration of 0.8
})

// outside animation block
view.layer.opacity = 0.5 // Will not animate

// inside MotionAnimator animation block
MotionAnimator.animate(withDuration: 0.8, animations: {
  view.layer.opacity = 0.5 // Will generate an animation with a duration of 0.8
})

CALayer key path	inside animation block	inside MotionAnimator animation block
`anchorPoint`	✓ (starting in iOS 11)	✓
`backgroundColor`		✓
`bounds`	✓	✓
`borderWidth`		✓
`borderColor`		✓
`cornerRadius`	✓ (starting in iOS 11)	✓
`bounds.size.height`	✓	✓
`opacity`	✓	✓
`position`	✓	✓
`transform.rotation.z`	✓	✓
`transform.scale`	✓	✓
`shadowColor`		✓
`shadowOffset`		✓
`shadowOpacity`		✓
`shadowRadius`		✓
`strokeStart`		✓
`strokeEnd`		✓
`transform`	✓	✓
`bounds.size.width`	✓	✓
`position.x`	✓	✓
`position.y`	✓	✓
`zPosition`		✓

Unflushed, unhosted CALayer

CALayers are unflushed until the next CATransaction.flush() invocation, which can happen either directly or at the end of the current run loop.

let layer = CALayer()

// inside animation block
UIView.animate(withDuration: 0.8, animations: {
  layer.opacity = 0.5 // Will not animate
})

// outside animation block
layer.opacity = 0.5 // Will not animate

// inside MotionAnimator animation block
MotionAnimator.animate(withDuration: 0.8, animations: {
  layer.opacity = 0.5 // Will generate an animation with a duration of 0.8
})

CALayer key path	inside animation block	outside animation block	inside MotionAnimator animation block
`anchorPoint`			✓
`backgroundColor`			✓
`bounds`			✓
`borderWidth`			✓
`borderColor`			✓
`cornerRadius`			✓
`bounds.size.height`			✓
`opacity`			✓
`position`			✓
`transform.rotation.z`			✓
`transform.scale`			✓
`shadowColor`			✓
`shadowOffset`			✓
`shadowOpacity`			✓
`shadowRadius`			✓
`strokeStart`			✓
`strokeEnd`			✓
`transform`			✓
`bounds.size.width`			✓
`position.x`			✓
`position.y`			✓
`zPosition`			✓

Flushed, unhosted CALayer

let layer = CALayer()

// It's usually unnecessary to flush the transaction, unless you want to be able to implicitly
// animate it without using a MotionAnimator.
CATransaction.flush()

// inside animation block
UIView.animate(withDuration: 0.8, animations: {
  // Will generate an animation with a duration of 0.25 because it uses the CATransaction duration
  // rather than the UIKit duration.
  layer.opacity = 0.5
})

// outside animation block
// Will generate an animation with a duration of 0.25
layer.opacity = 0.5

// inside MotionAnimator animation block
MotionAnimator.animate(withDuration: 0.8, animations: {
  layer.opacity = 0.5 // Will generate an animation with a duration of 0.8
})

CALayer key path	inside animation block	outside animation block	inside MotionAnimator animation block
`anchorPoint`	✓	✓	✓
`backgroundColor`			✓
`bounds`	✓	✓	✓
`borderWidth`	✓	✓	✓
`borderColor`	✓	✓	✓
`cornerRadius`	✓	✓	✓
`bounds.size.height`	✓	✓	✓
`opacity`	✓	✓	✓
`position`	✓	✓	✓
`transform.rotation.z`	✓	✓	✓
`transform.scale`	✓	✓	✓
`shadowColor`	✓	✓	✓
`shadowOffset`	✓	✓	✓
`shadowOpacity`	✓	✓	✓
`shadowRadius`	✓	✓	✓
`strokeStart`	✓	✓	✓
`strokeEnd`	✓	✓	✓
`transform`	✓	✓	✓
`bounds.size.width`	✓	✓	✓
`position.x`	✓	✓	✓
`position.y`	✓	✓	✓
`zPosition`	✓	✓	✓

Example apps/unit tests

Check out a local copy of the repo to access the Catalog application by running the following
commands:

git clone https://github.com/material-motion/motion-animator-objc.git
cd motion-animator-objc
pod install
open MotionAnimator.xcworkspace

Installation

Installation with CocoaPods

CocoaPods is a dependency manager for Objective-C and Swift libraries. CocoaPods automates the
process of using third-party libraries in your projects. See
the Getting Started guide for more
information. You can install it with the following command:
gem install cocoapods

Add motion-animator to your Podfile:

pod 'MotionAnimator'

Then run the following command:

pod install

Usage

Import the framework:

@import MotionAnimator;

You will now have access to all of the APIs.

Contributing

We welcome contributions!

Check out our upcoming milestones.

Learn more about our team,
our community, and
our contributor essentials.

License

Licensed under the Apache 2.0 license. See LICENSE for details.