October 25, 2014
by: Mike Woelmer
16 Comments

Unwind Segues in iOS Storyboards

Introduced in 2012 with iOS 6, Unwind Segues give you a way to “unwind” the navigation stack and specify a destination to go back to. The first time you use them, they can be confusing. In fact there’s no other UI feature of iOS development that has caused more discussion in our office than Unwind Segues. In this post, I’ll help you understand the fundamentals.

Unwind exit buttonEver since I noticed the strange “Exit” outlet show up in Xcode, I’ve wondered what it did. Most people probably did what I did the first time they saw it. I Ctrl-draged from a button to the “Exit” outlet and nothing happened. This is the beginning of the confusion for new developers. How do I get the “Exit” outlet to do anything?

I’m going to setup a simple example of three UIViewControllers in a UINavigationController.

Unwind example

I put a “Next” button on each view controller that goes from 1 to 3 in order. To do this I used “Show” or “Push” Segues as you normally would to go from one view controller to the next. I want to create an Unwind Segue that goes from 3 all the way to 1. I placed a “Home” button on UIViewController #3. When pressed, I want it to unwind all the way to #1.

Enable Unwind Segues 

To enable the Unwind Segue you need to add some code first. There are two things confusing about this:

  1. It’s backwards. Normally when you create an action outlet for a button, Interface Builder will create the code for you.  In this case Ctrl-dragging from the “Home” button to the “Exit” outlet is expecting code to already be in your project.
  2. Normally when you create an action outlet for a button, it puts the code in the same class that owns the button. For Unwind Segues, you need to put the code in the destination view controller. In my simple example the code needs to go in view controller #1 even though the button that is executing the segue is in #3.

So let’s look at what code we need to write for our Unwind Segue. I assigned a custom class for UIViewController #1 and added the following function:

-(IBAction)prepareForUnwind:(UIStoryboardSegue *)segue {
}

The signature of this function is key to Interface Builder recognizing it. It must have a return value of IBAction and take one parameter ofUIStoryboardSegue*. The name of the function does not matter. In fact, the function does not even have to do anything. It’s just there as a marker of which UIViewController is the destination of the Unwind Segue. Of course, you could put code in this function if you wanted to. You can inspect the identifier of the segue or access the source view controller and get at any properties you may need. The source view controller in my case would be #3.

Now that I have the code in place, I can return to Interface Builder and add our Unwind Segue.

Adding the Unwind Segue in Interface Builder

Unwind select actionThis time when you Ctrl-drag from the “Home” button to the “Exit” outlet, you will see a modal popup.

Interface Builder will search every UIViewController class in your project for functions with that particular signature and list them all in the pop-up. Select the function that we just added in the previous step. 

Now you will see the unwind segue added to the #3 view controller:

Unwind segue in document outline

And that’s all that it takes to get a simple Unwind Segue working. When you press the “Home” button, the runtime will walk the navigation stack backwards until it finds a UIViewController that implements the function I selected as my Unwind Segue Action (prepareForUnwind) and it will transition to that view controller.

This is the first part of my series on Unwind Segues: