Apple introduced storyboard references in iOS 9 and macOS 10.11 with the goal of making storyboards less daunting and easier to manage. Storyboard references allow you to break a storyboard up into multiple, smaller storyboards. A storyboard reference ties multiple storyboards together, creating one, large, composite storyboard.

Looking back, it is crazy that storyboard references made their way into the SDK years after the introduction of storyboards. Apple should have introduced them years ago. But better late than never.

Refactoring Storyboards

To illustrate how storyboard references work, I suggest we refactor an existing project. A few weeks ago, we created a notes application to explore the ins and outs of the NSFetchedResultsController class. Download the project from GitHub and open it in Xcode.

Build and run the application in the simulator to make sure everything is working. The project contains two storyboards:

  • Main.storyboard
  • LaunchScreen.storyboard

Main.storyboard contains the user interface of the application and it is this storyboard we focus on in this tutorial. This is what the storyboard currently looks like:

The Project's Main Storyboard Before Refactoring

Because the storyboard isn't overly complex, it is ideal for showing you how easy it is to break an existing storyboard up into multiple storyboards, using storyboard references.

To split an existing storyboard up into smaller pieces, we first need to select the scene (or scenes) that is going to be moved into a new storyboard and replaced with a storyboard reference.

Select the Note View Controller scene in Main.storyboard and choose Refactor to Storyboard ... from Xcode's Editor menu. Xcode prompts you to name the storyboard which the Note View Controller scene is moved to. Name the storyboard NoteViewController.storyboard and click Save.

By refactoring the Note View Controller scene to its own storyboard, Xcode does two things for us:

  • it creates a new storyboard, NoteViewController.storyboard
  • it replaces the scene in Main.storyboard with a storyboard reference

If you open NoteViewController.storyboard, you can see for yourself that it contains the Note View Controller scene. Note that the Note View Controller is the initial view controller of the storyboard.

The Note View Controller scene is moved to a separate storyboard.

More interesting is the storyboard reference that has replaced the Note View Controller scene in Main.storyboard. Open Main.storyboard, select the storyboard reference, and open the Attributes Inspector on the right.

Exploring the Attributes of a Storyboard Reference

The storyboard reference has three attributes:

  • Storyboard indicates which storyboard the storyboard reference references.
  • Referenced ID points to the identifier of the scene in the referenced storyboard. This attribute is currently blank, which means the initial view controller is the target scene of the storyboard reference.
  • Bundle points to the bundle to which the referenced storyboard belongs. If this attribute is left blank, it points to the bundle to which the storyboard containing the storyboard reference belongs.

These three attributes should give you an idea of the power and flexibility of storyboard references. You could, for example, hook into a storyboard of a library or framework, using nothing more than a storyboard reference.


Storyboard references are a welcome addition to storyboards and that is probably an understatement. This tutorial shows the immediate benefits of storyboard references:

  • breaking complex storyboards up into smaller storyboards
  • jumping to specific scenes in a storyboard
  • reusing storyboards and scenes

Storyboard references have more benefits, such as eliminating or reducing merge conflicts when working with multiple developers on a project. Storyboards and source control don't always go well together. Storyboard references should make this easier by adding the ability to break storyboards up into manageable pieces.


The only drawback of storyboard references is their availability. Storyboard references were introduced in iOS 9 and macOS 10.11. This may mean that you won't be able to use them in existing projects. But nothing is stopping you from using them in some of your side projects.

What's Next?

If you are lucky and can target iOS 9 or macOS 10.11, then I encourage you to give storyboard references a try. They may make you reconsider your opinion about storyboards. Storyboards offer many advantages over XIB files or creating an application's user interface in code. With the addition of storyboard references, you no longer have an excuse to not use storyboards.

Questions? Leave them in the comments below or reach out to me on Twitter. You can download the source files of the tutorial from GitHub.