iOS Storyboards: Getting Started
- Getting Started
- Understanding Storyboard Previews
- Designing Your Storyboard
- Just Add It to My Tab
- Understanding the Error
- Specifying the Initial View Controller
- Building the Players List
- Creating the Navigation Controller
- Reconnecting the Tab Controller
- Giving Tabs an Identity
- Using Table Cells
- Customizing Players’ Cells
- Adding Constraints
- Fixing the Layout Issues
- Adding Items to Your List
- Building the Add Player Scenes
- Connecting Scenes Through Segues
- Constructing the Form
- Setting Up the Cells
- Creating the Games List
- Making a Gesture
- Labeling Storyboard Elements
- Connecting the Gestures
- Changing the Presentation Animation
- Where to Go From Here?
Storyboards are an exciting feature first introduced in iOS 5, which save time building user interfaces for your apps. Storyboards allow you to prototype and design multiple view controller views within one file, and also let you create transitions between view controllers.
Before storyboards, you had to use XIB files (aka NIB files). You could only use one XIB file per view (for example, per
UITableView or other supported
The following image shows you what a storyboard looks like. It’s similar to the storyboard you’ll build during this tutorial:
You may not know what this app does, but you can see its scenes and how they’re related.
In this tutorial, you’re going to build Ratings, a prototype app that shows a list of players, the games they play and their skill rating. You’ll learn common tasks that you can accomplish using storyboards, like creating scenes and wiring up view controllers. And you’ll do all of this without a single line of code. :]
Download everything you need for this tutorial by using the Download Materials button at the top or bottom of this page. There’s no starter project, but there’s a folder named Images containing assets that you’ll need later.
Now, open Xcode and create a new iOS app using the Single View Application template.
Fill in the template options as follows, then click Next and then Create:
- Product Name: Ratings.
- Organization Name: Fill this in however you like.
- Organization Identifier: The identifier you use for your apps.
- Language: Swift.
- User Interface: Storyboard.
- Make sure you’ve unchecked the Use Core Data, Include Unit Tests and UI Tests options.
After you finish, the main Xcode window should look like this:
The new project consists of six files:
- Main.storyboard, the star of this tutorial
You don’t need to change anything in the .swift files in this tutorial, so don’t worry about them.
Under Deployment Info in the General project settings, uncheck iPad. Find Device Orientation and, since this is a portrait-only app, uncheck the Landscape Left and Landscape Right options.
Understanding Storyboard Previews
Open Main.storyboard in the Project navigator to view it in the Interface Builder editor:
Here, you see a single view controller containing an empty view. The arrow pointing to the view controller from the left indicates it’s the initial view controller for this storyboard. You’ll learn about this in more detail later.
You’ll notice the default scene size is for a 4.7-inch screen. Xcode enables Auto Layout and Size Classes by default for storyboards. They allow you to make flexible user interfaces that can resize easily, which is useful for supporting various sizes of iPhones and iPads.
To change the scene size to another device, click the button at the bottom-left of the storyboard. You’ll then be able to select from the full range of supported device sizes, from the iPad Pro (12.9-inch) to the iPhone 4s (3.5-inch), in both portrait and landscape orientations.
Designing Your Storyboard
To design the layout in the storyboard editor, drag controls from the Object Library and drop them into your scene in the position you want. You can change their position or remove them later.
You’ll rely heavily on the Object Library to design your storyboards. Before you start on the app, there’s one more item on the screen you should know about: The Document Outline.
The Document Outline shows all the items you have inside the open storyboard file, as well as any view controller and any of the controls it includes. View controllers are called scenes on the storyboard. In this tutorial, you’ll use the name “scene” to refer to the view controller inside your storyboard.
The Document Outline will be one of your main navigation points to select the elements of the storyboard.
Now, it’s time to start building the Ratings app.
Just Add It to My Tab
The app you’re about to build has a tabbed interface with two scenes. To add the tabbed interface, start by opening Main.storyboard and deleting the only scene there. Simply click on View Controller in the Document Outline and press the delete key on your keyboard.
Drag a tab bar controller from the Object Library into the canvas. You can filter the list by typing part of the name of the item you’re looking for.
Tab bar controller comes pre-configured with two additional view controllers, one for each tab. It’s a so-called container view controller because it contains one or more other view controllers. Other common containers are the Navigation controller and the Split View controller.
The arrows between the tab bar controller and the view controllers it contains represent the container relationship. The icon shown below, in the middle of the arrow body, signifies that they have an embed relationship.
Build and run and you’ll see something like this in the console:
Ratings[9912:704408] [WindowScene] Failed to instantiate the default view controller for UIMainStoryboardFile 'Main' – perhaps the designated entry point is not set?
Don’t panic! :] That error simply indicates that the app didn’t find the initial view controller to show. Before you fix this, take a moment to understand what’s going on.
Understanding the Error
First, the error message mentioned the name of your storyboard, Main, explicitly. It’s not a keyword, so how did Xcode know that this is the storyboard file it should be loading at the beginning of your app?
To understand that, open the application settings by selecting the project file from the Project navigator, selecting Ratings from the Targets list and making sure that you’ve selected the General tab at the top.
In this settings screen, you’ll see that the value in the drop-down for Main Interface is Main. This drop-down will only show the storyboard files in your project.
Specifying the Initial View Controller
Keep Main as the selected value and move to the next step: Identifying the specific view controller you want to start with inside that storyboard.
Open Main.storyboard and select the Tab Bar Controller Scene. On the right, select the Attribute inspector.
You’ll find a checkbox named Is Initial View Controller.
Checking this box will identify the selected view controller as the initial entry point for the storyboard you’re on. Also, an arrow will appear on the left of the view controller.
Now, build and run and you’ll see an empty view controller with a tab bar that has two items at the bottom.
Xcode comes with a template for building a tabbed app: The Tabbed Application template. You could have used it here, but it’s good to know how to build one yourself so you can create a tab bar controller by hand, if you have to.
Building the Players List
It’s time to build the first screen in your app. Currently, the two screens attached to the tab bar controller are both
UIViewController instances. You’re going to replace the first tab scene with a
Click the first view controller in the Document Outline to select it, then delete it. Drag a new table view controller into the canvas where the previous scene used to be:
Creating the Navigation Controller
You want to place the table view controller inside a navigation controller. Select the table view controller and choose Editor ▸ Embed In ▸ Navigation Controller from Xcode’s menu bar. This adds another controller to the canvas:
You could have dragged in a navigation controller from the library and embedded the table view, but this Embed In command is a nice time-saver for a common action.
Navigation controller is also a container view controller, and it has a relationship arrow pointing to the table view controller. You can see it in the Document Outline:
Notice that embedding the table view controller gave it a navigation bar. Interface Builder automatically put it there because this scene will now appear inside the navigation controller’s context.
Reconnecting the Tab Controller
Deleting the first scene also deleted its relationship with the tab bar controller. But now, you want to recreate it. Instead of connecting it to the Table View Controller Scene, you’ll connect it to the Navigation Controller Scene.
To do this, Control-drag from the tab bar controller to the navigation controller. When you let go, a small pop-up menu will appear. Choose the Relationship Segue – view controllers option:
This creates a new relationship arrow between the two scenes. This is also an embed relationship, like the one you saw earlier. The tab bar controller has two embed relationships, one for each tab. The navigation controller itself has an embed relationship with the table view controller.
When you made this new connection, a new tab was added to the tab bar controller named Item. For this app, you want this new scene to be the first tab, so drag the tabs around to change their order:
Build and run to try it out. The first tab now contains a table view inside a navigation controller.
Giving Tabs an Identity
In their current state, the tabs are not expressive at all. Each should have its own icon and name to represent its views. The first tab’s name should be “Players” and the second should be “Gestures”.
When any a controller is connected to a tab, it automatically has an instance of
UITabBarItem. This instance defines the name and the image that should appear on the tab bar.
In the Document Outline, under the Item 2 Scene, you will find an item named Item 2 that has a star icon beside it. Select it and, in the Attributes inspector, change its Title to Gestures.
Now, try another way to set the title. In the navigation controller, double-click the word Item at the bottom of the tab bar and type the new name Players.
You can add the images now. Open Assets.xcassets from the Project navigator then drag the Images folder from the download materials into it.
Back in Main.storyboard, use the Attributes inspector to change the images of the two tab items you just renamed using their matching images.
Build and run and marvel at your pretty tab bar. As promised, you haven’t needed a single line of code to come this far… and you’re just getting started. :]
Using Table Cells
So far, the Players tab shows an empty list because the table view in this screen has no cells. There are two ways a table view can operate:
- Dynamic prototypes allow you to build cells on the storyboard to create multiple copies of them. You can only instantiate them through code.
- Static cells will appear exactly the way you designed them in the storyboard. They don’t need any code to instantiate.
In most cases, you’ll use dynamic prototypes in your apps, but since the objective of this tutorial is to build a prototype with zero code, you’ll use static cells instead. Don’t worry, it’s easy to switch between them when you start building the code.
Select the table view and, from the Attributes inspector, change the value of the Content drop-down to Static Cells. Now, you can customize the cells.
Customizing Players’ Cells
The storyboard now shows three empty cells in the table view. Go ahead and delete two of them.
Select the remaining cell and change its Accessory to Disclosure Indicator.
Drag a Horizontal Stack View onto your cell. Then, within the horizontal stack, add a Vertical Stack View and an Image View. Finally, add two labels within the Vertical Stack View.
Your Document Outline should look like this now.
Wait, what’s that red circle doing there? That’s a warning that the views you added have no idea how to position themselves in the cell. As your app runs on different devices with different screen sizes, the cell’s size will change. This is where Auto Layout comes in.
Select the Horizontal Stack view you added in the cell, then click on the Add New Constraints button that looks like a tie fighter.
That button will open a dialog that lets you specify constraint values. Specify the constraints to add for the Stack view as follows:
When you’re done, select the image and give it a Width constraint of 81.
Fixing the Layout Issues
With each set of constraints you add, the controls on the storyboard adjust their positions to match.
It’s important to avoid any layout errors, and right now, there’s still an error. Sometimes, Xcode is able to suggest the constraints you need to add to fix it. In this case, those suggestions will work, but remember that Xcode won’t always be right in future cases. :]
Click on the small red circle and it will show you the layout errors. Click the new red circle and tap Change Priority.
Change the font size of the lower label to 14 and set the image of the Image view to 4Stars. Then, use the Size inspector to change the default height of the cells in the table view to 60 and uncheck Automatic for both the table view and the cell.
Adding Items to Your List
A list isn’t really a list when it only has a single item. You can either duplicate the cells you just created or tell the table view to show more. In this case, you’ll do the latter.
Select Table View Section from the Document Outline and, in the Attributes inspector, set the number of Rows to 3.
Your last step is to give your cells some real data. Enter some people’s names and some games, then change some images to rate them. And don’t forget to give this screen a title: Just double-click on the empty space above the table view and type Players.
Build and run; you should see the list you just created.
Your next step is to build a view to let the user add a new player.
Building the Add Player Scenes
This screen will not be functional without code to make it work, but nothing is holding you back from creating the interface for these forms.
To start, you’ll add a “+” button in the top-right corner of the Players Scene.
Add a Bar Button Item to the upper-right corner of the scene. The corner will highlight automatically as you drag the button over that area. Then, change its System Type to Add.
The Add button should open a new scene with a form for the user to enter the player’s information; you’ll create that form next.
Connecting Scenes Through Segues
Drag a navigation controller onto your scene. It will come with a table view controller. Then, control-drag from the Add button to the newly-added navigation controller. Select Show from the pop-up menu.
Build and run, then tap the Add button.
You will see the new view controller appear from the bottom of the screen. When you drag or swipe that scene down from its header, you dismiss it.
The connection you created from the Add button to the navigation controller is called a Segue. And since it came from an interactive element on the screen, namely the button, you trigger the segue by tapping the button it’s connected to.
Apple introduced this card-like presentation in iOS 13. Previously, any view controller presented like this would take the full screen, and you needed a couple of lines of code to dismiss it. So iOS 13 made things look nicer with no code at all … That’s what’s called a double win! :]
Constructing the Form
The form you want to create should look like this:
In the newly-created view controller, double-click on its title from the storyboard and change it to Add Player. Then add two Bar Button Item instances, one to the upper-left corner and one to the upper-right corner. Change the System Type of the left one to Cancel and the one on the right to Done.
Next, select the table view in that scene, change its Content to Static Cells and change Sections to 2. Each section has three rows. You only need one under each section, so delete the last two.
Finally, change the Style of the table view to Grouped, the header of the first section to Player name and use an empty string for the title of the second one.
Build and run, then tap the + button to open the Add Player form. It should look like this:
Setting Up the Cells
The cell in the first section should be a text field. So drop a Text Field on the cell. Then change the Border style of that field to None.
Once you change its style, the control corners of the bounding box of the text field will appear. Manually set its size to fit the cell – yes without constraints – it will work. :]
In the first table view you created, you added each element you wanted inside the cell. Xcode also provides a few presets for table cells that you can choose from. They may not always fit your needs, but in some simple cases, they fit nicely.
To try them out, select the cell in the second section then change its Style to Right Detail and the Accessory to Disclosure Indicator. Double-click the word Title and replace it with Game.
Build and run and check that your form looks exactly like this:
Now, you can populate the list of games.
Creating the Games List
When you tap the second cell, it should open the list of available games to choose. This list should look like this:
This needs another table view controller, so add one to your storyboard now. Change the Content of its table view to Static Cells, and change the Style of the cells already inside it to Basic. Then select the Table View Section and increase the number of rows to six.
Change the titles of the rows to some games you like, and for only one of them, change the Accessory to Checkmark.
So far, this scene has no entry points; you want it to open when you tap the second cell in the Add Player screen. To make that happen, you’ll connect the scene the same way you connected the Add button to the navigation controller.
Control-drag from the second cell to the new scene. Select Show from the pop-up.
Notice that a back button appeared in the second scene after you made the connection. This is because the Show action here will push the second scene to the navigation controller that’s already there. Navigation controllers automatically provide a back button to any additional view controllers that are pushed inside them.
Build and run and celebrate the Ratings app. As promised, you didn’t need a single line of code to accomplish so much. :]
Did you know you can also use gestures in storyboards? Here’s how.
Making a Gesture
Gestures are another control you can use directly on storyboards. In this section, you’ll learn how to use them… without any code, as usual. :]
Add two Swipe Gesture Recognizers to the Gestures Scene.
In the Attributes inspector, set the Swipe direction of the first to Left, and the second to Right.
Notice that their names in the Document Outline are identical, although each has a different direction. This makes it slightly harder to identify your objects later on. Right now, it doesn’t feel hard because you remember their order, but will you still remember it tomorrow?
Labeling Storyboard Elements
A better name would help you remember what your gestures do. Xcode allows you to change the name that appears in the Document Outline, which has no effect at runtime.
To change the name, select the first recognizer then, in the Identity inspector, change the value of the Label to Swipe Left Gesture. Do the same thing with the second recognizer to change the name to Swipe Right Gesture.
Their names will now appear like this:
Now that you’ve added the swipe gestures and they’re easily recognizable, you can start making some use for them. Add two new view controllers and add a label in the center of each to identify them when they’re open.
Connecting the Gestures
Select your Swipe Left Gesture and open the Connections inspector. In the Triggered Segues section, drag from the small circle on the right of action to the view controller you want to open from that swipe. Select Show from the pop-up.
Do the same for the Swipe Right Gesture and the other view controller.
Build and run, then select the Gestures tab and swipe left or right. The swipe action will present the view controllers they’re connected to. When you swipe the new scene down, it will close.
Changing the Presentation Animation
UIKit offers different presentation styles and animations, and you can change your style directly from the storyboard. Select any of the two new view controllers and open the Attributes inspector.
The Transition Style defines how the scene will animate when it presents. And the Presentation sets the way this scene displays, regardless of the animation type.
Not all Transition Style animations work with all Presentation values. For example, Partial Curve won’t work with the new presentation style provided by iOS 13. To try it, you must change Presentation to Full Screen.
Feel free to explore them and see the different animations you can perform by simply changing a value from a drop-down list. All this without any code at all. :]
Where to Go From Here?
In this tutorial, you learned a lot about the power of storyboards, including:
- Building your interface using the Object Library and customizing that interface.
- Connecting screens through segues and making your app interactive without writing any code.
- Customizing names and labels in the Document Outline.
- Changing the transition animations between view controllers.
If you want to build faster and more powerful interfaces, you’ll want to learn more about Auto Layout. Auto Layout is a very powerful tool to define the layout of your screens, the better you are with it, the more sophisticated your apps will be.
To take the next step and turn this storyboard into a full app, check out iOS Storyboards: Segues and More.
If you have any questions or comments, please don’t hesitate to join the forum discussion below.