Guide · Open source
How to use Hero: iOS view controller transitions guide
Updated · written with AI from the project's own documentation and checked against our catalogue data
Hero is an open-source Swift library for building custom animations between view controllers in iOS and tvOS apps. It sits on top of UIKit's transition APIs, which the README describes as cumbersome, and gives you a declarative way to describe them. This guide shows you how to install it, match views with heroID, add motion with heroModifiers, and enable template transitions so you can build your own.
HeroHeroTransitions/Hero · ★ 22.5k · MIT Install options & downloads Quick start
- 1Install the library. Add pod 'Hero' to your Podfile and run pod install, or use another package manager from the README.
- 2Import Hero. Add import Hero to every Swift file where you use it.
- 3Enable Hero on the view controllers. Set self.hero.isEnabled = true on the view controllers involved in the transition.
- 4Set matching heroIDs. Assign the same hero.id string to the source and destination views you want Hero to match.
- 5Add heroModifiers. Set hero.modifiers on unmatched views to describe how they should move, fade, or scale.
- 6Pick a template transition. Set heroModalAnimationType, heroNavigationAnimationType, or heroTabBarAnimationType as a base for your transition.
- 7Test the transition. Run the app and check the transition. If views are hidden behind others, apply useGlobalCoordinateSpace.
What Hero does and when to use it
Hero checks the heroID property on all source and destination views. Each matched pair is animated from its old state to its new state, similar to Keynote's Magic Move. Unmatched views can be animated with heroModifiers, and all of these animations can be controlled interactively by user gestures.
Hero is a good fit if you build iOS apps with UINavigationController, UITabBarController, or modal presentations and want custom transitions without writing low-level UIKit animation code. If the standard iOS transitions already do what you need, Hero may not be necessary.
- Best for shared-element style transitions between matching views
- Works with Auto Layout, programmatic layout, UICollectionView, and UITableView, according to the README
- Not for Android, web, or other non-Apple platforms
Install Hero with CocoaPods, Carthage, Accio or Swift Package Manager
The README lists four package-manager options and a manual method. The CocoaPods route is the shortest: add the Hero entry to your Podfile, then run pod install.
Remember to import Hero in every file where you use it.
- CocoaPods: add pod 'Hero' to your Podfile, then run pod install
- Carthage: add github "HeroTransitions/Hero" to your Cartfile, then run carthage update
- Accio: add the Hero package to Package.swift and run accio update
- Swift Package Manager: add the Hero package as a dependency in Package.swift
- Manual: drag the Sources folder into your project
pod 'Hero'Match views across screens with heroID
Give matching views the same heroID on both view controllers. Hero then animates each matched pair between its position and appearance on the first screen and on the second. Enable Hero on the view controller with hero.isEnabled set to true.
Note that Hero's ID is set through the hero.id property on each view.
- Set hero.id to the same string on the source view and the destination view
- Set self.hero.isEnabled = true on the view controller that takes part in the transition
redView.hero.id = "ironMan"
blackView.hero.id = "batMan"Add motion to unmatched views with heroModifiers
Views without a matching ID can still animate. Set hero.modifiers on them to describe the change, such as translating a view. Combine modifiers in an array.
For a group of views, you can set a modifier on the parent view, such as cascade, and apply per-view modifiers to its children.
- Use .translate(y:) to move a view during the transition
- Use .fade and .scale(_:) together on several cells
- Use .cascade on a parent view to stagger its children
self.hero.isEnabled = true
redView.hero.id = "ironMan"
blackView.hero.id = "batMan"
whiteView.hero.modifiers = [.translate(y:100)]Use template transitions for navigation, modal and tab bar
Hero provides template transitions you can set on a view controller through heroModalAnimationType, heroNavigationAnimationType, and heroTabBarAnimationType. Use them as a starting point, then combine them with heroID and heroModifiers for your own effects.
To use a different default animation when dismissing, use .selectBy(presenting:dismissing:). The README's example uses .zoom for presenting and .zoomOut for dismissing. The README also shows the settings can be made in the storyboard.
- If a push or pop inside a navigation controller does not animate, enable hero.isEnabled on the navigation controller too
- To remove the default push animation, set the navigation animation type to .fade or .none
self.hero.modalAnimationType = .selectBy(presenting:.zoom, dismissing:.zoomOut)Fix views covered during a transition
Matched views use the global coordinate space, while unmatched views use the local one by default. A local-space view can end up behind a global-space view. The README's fix is the useGlobalCoordinateSpace modifier on the views being covered. The Coordinate Space wiki page has more detail.
For full API reference, the README points to the wiki Usage Guide and the header documentation, which you can open in Xcode with alt+click.
- Apply useGlobalCoordinateSpace to the covered views
- Check the Usage Guide wiki and the Dash-compatible API docs for details
What people use it for
- Animating a tapped thumbnail into a full-size image on a detail screen
- Staggering the appearance of cells in a collection view when a new screen opens
- Adding a custom push or modal animation to an iOS app that uses UINavigationController
- Making a gesture-driven dismissal that can be interactively controlled
Frequently asked questions
Is Hero free to use?
Yes. The repository is licensed under the MIT License, as shown in the README's license badge. Check the LICENSE file in the repository for the full terms.
How do I install Hero?
The README covers CocoaPods, Carthage, Accio, Swift Package Manager and manual installation. For CocoaPods, add pod 'Hero' to your Podfile and run pod install.
What are the requirements for Hero?
The README lists Xcode with Swift 4.0 or later support, with badges showing Xcode 10.0+ and iOS 10.0+. It also names CocoaPods, Carthage, Accio, or Swift Package Manager as ways to install it.
Does Hero work on Android or the web?
No. The README says Hero is for iOS and tvOS only.
Why is my Hero transition not working?
First check that self.hero.isEnabled is true on the view controller. If you push or pop inside a navigation controller, enable it on the navigation controller too.
Can I use Hero without writing code?
Not entirely. The README says you can set up animations in Swift code or in the storyboard, so some setup is still required.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Hero suits iOS and tvOS developers who want custom or shared-element transitions without hand-writing UIKit animation code, and who are comfortable with Swift or storyboard settings. If you only need the standard iOS transitions, or you build for Android, the web, or another platform, pick a different approach.
Install options & downloads