Swiftpack.co - Package - cashapp/stagehand


CI Status Version License Platform

Stagehand provides a modern, type-safe API for building animations on iOS. Stagehand is designed around a set of core ideas:

  • Composition of Structures - Stagehand makes it easy to build complex, multi-part animations that are built from small, reusable pieces that are easier to reason about.
  • Separation of Construction and Execution - Stagehand provides separate mechanisms for the construction and execution, which increases the flexibility of animations and makes concepts like queuing a series of animations work straight out of the box.
  • Compile-Time Safety - Stagehand uses modern Swift features to provide a compile-time safe API for defining animations.
  • Testability - Stagehand builds on the concept of snapshot testing to introduce a visual testing paradigm for animations.



To install Stagehand via CocoaPods, simply add the following line to your Podfile:

pod 'Stagehand'

To install StagehandTesting, the animation snapshot testing utilities, add the following line to your test target definition in your Podfile:

pod 'StagehandTesting'

Swift Package Manager

To install Stagehand via Swift Package Manager, add the following to your Package.swift:

dependencies: [
    .package(url: "https://github.com/cashapp/stagehand", from: "3.0.0"),

Getting Started with Stagehand

An animation begins with the construction of an Animation. An Animation is generic over a type of element and acts as a definition of how that element should be animated.

As an example, we can write an animation that highlights a view by fading its alpha to 0.8 and back:

var highlightAnimation = Animation<UIView>()
highlightAnimation.addKeyframe(for: \.alpha, at: 0, value: 1)
highlightAnimation.addKeyframe(for: \.alpha, at: 0.5, value: 0.8)
highlightAnimation.addKeyframe(for: \.alpha, at: 1, value: 1)

Let's say we've defined a view, which we'll call BinaryView, that has two subviews, leftView and rightView, and we want to highlight each of the subviews in sequence. We can define an animation for our BinaryView with two child animations:

var binaryAnimation = Animation<BinaryView>()
binaryAnimation.addChild(highlightAnimation, for: \.leftView, startingAt: 0, relativeDuration: 0.5)
binaryAnimation.addChild(highlightAnimation, for: \.rightView, startingAt: 0.5, relativeDuration: 0.5)

Once we've set up our view and we're ready to execute our animation, we can call the perform method to start animating:

let view = BinaryView()
// ...

binaryAnimation.perform(on: view)

Running the Demo App

Stagehand ships with a demo app that shows examples of many of the features provided by Stagehand. To run the demo app, open the Example directory and run:

bundle install
bundle exec pod install
open Stagehand.xcworkspace

From here, you can run the demo app and see a variety of examples for how to use the framework. In that workspace, there is also a playground that includes documentation and tutorials for how each feature works.


We’re glad you’re interested in Stagehand, and we’d love to see where you take it. Please read our contributing guidelines prior to submitting a Pull Request.


Copyright 2020 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.


Stars: 82


Used By

Total: 0


3.0.0 - 2020-09-18 05:14:53

  • Updates CGAffineTransform interpolation to use matrix decomposition. This improves the interpolation of non-RST transforms and greatly improves performance for all transform interpolation.
  • Adds support for animating CATransform3D using matrix decomposition.

2.1.1 - 2020-05-29 19:14:58

  • Fixes the execution of execution blocks and property assignments in curved animations

2.1.0 - 2020-04-09 21:38:09

  • Removes a limitation around subelement mutability when adding child animations.

2.0.4 - 2020-03-18 02:37:54

  • Updates handling of execution and per-frame execution blocks in child animations so they behave properly when used in a parent with a curve applied.
  • Delays calling the completion handler until the final frame of the animation is drawn to screen, to fix a bug where the drawing of the final frame would be delayed if the completion handler did a significant amount of work.

2.0.3 - 2020-03-06 07:31:36

  • Adds support for installing Stagehand via Swift Package Manager

2.0.2 - 2020-02-22 00:35:39

  • Fixes an issue where execution blocks and property assignments in child animations were not executed at the correct time.

2.0.1 - 2020-02-13 21:36:59

  • Makes the weak framework linking of XCTest explicit in the StagehandTesting podspec

2.0 - 2020-02-10 23:42:50

  • Adds snapshot methods for snapshotting an animation via a non-element view
  • Switches animated snapshot format from GIF to APNG