Spruce iOS Animation Library

Spruce is a lightweight animation library that helps choreograph the animations on the screen. With so many different animation libraries out there, developers need to make sure that each view is animating at the appropriate time. Spruce can help designers request complex multi-view animations and not have the developers cringe at the prototype.

Here is a quick example of how you can Spruce up your screens!

Installation Instructions

To make everything super easy, we currently support both CocoaPods and Carthage. If you want to just do everything yourself without a package manager, checkout our releases page and download the pre-built frameworks there or you can download the exact source from this Github project.

CocoaPods

Add the following to your Podfile.

pod "Spruce", '~> 1.0.0'

Carthage

Add the following to your Cartfile.

github "willowtreeapps/spruce-ios"

Getting Started

Spruce is entirely written in Swift and currently only supports Swift. Objective C wrappers are coming soon.

Basic Usage

Spruce comes packed with UIView extensions meant to make your life easier when calling an animation. Let's say we want to [.fadeIn, .expand(.slightly)] our view. We will call that array of animations ourAnimations.

Preparing for Animation

If you want a view to fade in, then you need to make sure that it is already faded out. To do that, we need to prepare the view. Spruce makes this easy by calling:

yourView.spruce.prepare(ourAnimations)

This prepare function will go through each view and set the alpha = 0.0 and also shrink the view so that when the animation runs the view will revert to it's original position.

Running the Animation

Use the following command to run a basic animation on your view.

yourView.spruce.animate(ourAnimations)

Checkout the documentation for more functions and how to better use the animate method.

Using a SortFunction

Luckily, Spruce comes with around 8 SortFunction implementations with a wide open possibility to make more! Use the SortFunction to change the order in which views animate. Consider the following example:

let sortFunction = LinearSortFunction(direction: .topToBottom, interObjectDelay: 0.1)

In this example we have created a LinearSortFunction which will have views animate in from the top to bottom. We can change the look and feel of the animation by using a RadialSortFunction instead which will have the views animate in a circular fashion. If we wanted to use this sortFunction in an actual Spruce animate call then that would look something like:

yourView.spruce.animate([.fadeIn, .expand(.slightly)], sortFunction: sortFunction)

Definitely play around with the stock SortFunction implementations until you find the one that is perfect for you! Check out the example app if you want to get previews of what each SortFunction will look like.

Using a Custom Animation

Though Spruce comes with a ton of stock animations, sometimes it is easier to make your own. We definitely encourage customization and Spruce is ready for it! Let's say you want to transform and animate a UIView object. To do let's create a PrepareHandler:

let prepareHandler = { view in
	view.transform = CGAffineTransform(scaleX: 0.1, y: 0.1)
}

The prepareHandler will be passed a UIView object by Spruce and then it is your functions job to get the view ready to animate. This way our animation will look clean and quick since the view is already scaled down and ready to grow! Now to setup the function to grow the view we need to create a ChangeFunction:

let changeFunction = { view in
	view.transform = CGAffineTransform(scaleX: 1.5, y: 1.5)
}

In changeFunction the same view will also be passed in by Spruce and then your function will be used to animate the actual view itself. These two functions will be called with each subview of the view you are animating. Now that we have both functions we are ready to create an animation:

let animation = StockAnimation.custom(prepareFunction: prepareHandler, animateFunction: changeFunction)

Once we have the animation all we need to do is pass that animation into Spruce and let the animation begin!

yourView.spruce.animate([animation])

GitHub