Hero is a library for building iOS view controller transitions. It provides a layer on top of the UIKit's cumbersome transition APIs. Making custom transitions an easy task for developers.
Hero is similar to Keynote's Magic Move. It checks the heroID
property on all source and destination views. Every matched view pairs are then automatically transitioned from its old state to its new state.
Hero can also construct animations for unmatched views. It is easy to define these animations via the heroModifiers
property. Hero will run these animations alongside the Magic Move animations. All of these animations can be interactively controlled by user gestures.
At view controller level, Hero provides several template transitions that you can set through heroModalAnimationType
, heroNavigationAnimationType
, & heroTabBarAnimationType
. These can be used as the foundation of your custom transitions. Combine with heroID
& heroModifiers
to make truly some unique transitions.
By default, Hero provides dynamic duration based on the Material Design Motion Guide. The duration is determined by the distance & size change. It save you the hassle while providing consistent and delightful animations.
Hero does not make any assumption about how the view is built or structured. It will not modify any of your views' states other than hiding them during the animation. This makes it work with Auto Layout, programmatic layout, UICollectionView (without modifying its layout object), UITableView, UINavigationController, UITabBarController, etc...
Example Gallery
Checkout the Example Gallery Blog Post for a general idea of what you can achieve with Hero
Usage Example 1
View Controller 1
redView.heroID = "ironMan"
blackView.heroID = "batMan"
View Controller 2
isHeroEnabled = true
redView.heroID = "ironMan"
blackView.heroID = "batMan"
whiteView.heroModifiers = [.translate(y:100)]
Usage Example 2
View Controller 1
greyView.heroID = "skyWalker"
View Controller 2
isHeroEnabled = true
greyView.heroID = "skyWalker"
// collectionView is the parent view of all red cells
collectionView.heroModifiers = [.cascade]
for cell in redCells {
cell.heroModifiers = [.fade, .scale(0.5)]
}
You can do these in the storyboard too!
Documentations
Checkout the WIKI PAGES (Usage Guide) for documentations.
For more up-to-date ones, please see the header-doc. (use alt+click in Xcode)
Interactive Transition Tutorials
Interactive transitions with Hero (Part 1)
FAQ
White flashes occurs on iPhone 7 (Plus) Simulators
Hero does not work on iPhone 7 (Plus) Simulators due to an Apple bug. Please use other simulators or a real device when working with Hero.
isHeroEnabled
is set to true
Not able to use Hero transition even when Make sure that you have also enabled isHeroEnabled
on the navigation controller if you are doing a push/pop inside the navigation controller.
Views being covered by another matched view during the transition
Matched views use global coordinate space while unmatched views use local coordinate space by default. Local coordinate spaced views might be covered by other global coordinate spaced views. To solve this, use useGlobalCoordinateSpace
modifier on the views being covered. Checkout Coordinate Space Wiki page for details.
Weird behavior with UIVisualEffectView
UIVisualEffectView is quite hard to animate due to the private implementation and incompatibility with snapshotAfterScreenUpdate
and some Core Animation APIs. We are trying to get these solved as much as we can. Currently, as of 0.3.2, only unmatched UIVisualEffectView with noninteractive .fade
animation is supported.
Push animation is shown along side my custom animation
This is the default animation for navigation controller provided by Hero. To disable the push animation, set heroNavigationAnimationType
to .fade
or .none
on the navigation controller.
Contribute
We welcome any contributions. Please read the Contribution Guide.