Tab Bar Controllers

Tab Bar Controllers are different from Navigation Controllers. They can contain Navigation Controllers inside of it, but Navigation Controllers can't contain Tab Bar Controllers inside them.

You could see Tab Bar Controllers in on your iOS device. They are just horizontal buttons in the very bottom of your screen that group application screens by some property. When you tap on one of the Tab Bar buttons, it will take you to another screen.

Tab Bar Controllers usually take a lot of code to initialize in a plain Objective-C-style code:

        def application(app, didFinishLaunchingWithOptions: options)
          # create screens:
          first_screen =
          second_screen =

          # we want our screens to be inside of a Navigation Controller:
          nav_controller_first = UINavigationController.alloc.initWithRootViewController first_screen
          nav_controller_second = UINavigationController.alloc.initWithRootViewController second_screen

          # create array of our tabs (screens):
          tabs = [nav_controller_first, nav_controller_second]

          # now creating a Tab Bar Controller:
          tab_bar =
          tab_bar.delegate = self

          # and setting our tabs on a tab bar:
          tab_bar.viewControllers = tabs

          @window = UIWindow.alloc.initWithFrame(UIScreen.mainScreen.bounds)
          @window.rootViewController = tab_bar
Good thing that we have ProMotion. Instead of 23 lines of code, we can use only 4:
        def on_load(app, opts={})
          # create a tab bar with 2 screens, each inside Navigation Controller
          open_tab_bar true,
The result will be the same in both cases: tab bar controller with two screens, each inside of a Navigation Controller.

To make your tab look better, we can use ProMotion's class method tab_bar_item to set custom icons and titles. Let's set them on both of our screens:

        class MoodHistoryScreen < PM::Screen
          title "Mood History"
          tab_bar_item system_item: UITabBarSystemItemHistory

          # MoodHistoryScreen code continues ...


        class HomeScreen < PM::Screen
          tab_bar_item title: "Home", item: "images/home"

          # HomeScreen code continues ...
system_item here means that we are going to use system icon instead of our own. You can draw a custom icon yourself, and specify its name in the item: "your_icon" and tab title in the title: "Custom Title". In our example, we used system History icon (title has been also set automatically). For a Home screen, I draw a small icon named home.png in 3 sizes (3@, 2@, 1@), and put it inside /resources/images. Result looks like this:

To see the list of all available system icons, you can visit Apple Docs

As usual, all main interactions with Tab Bar Controller don't need any additional code: user can switch between tabs and iOS will automatically highlight active tab, will change text and image color, etc. If you want to do it programmatically, you can always use the open_tab method with specified tab title or its index (starting from 0). If you need to do some custom stuff when a user selects the tab, you can use delegate method on_tab_selected(screen):

        def on_tab_selected(screen)
          # some action


Tab Bars Controllers used to switch between multiple screens. When a user selects some tab, the controller will open root view controller for a given tab. Remember that Tab Bar Controllers can contain Navigation Controllers, but it can't be the other way: Tab Bar Controller can't be inside of any other controller - it has to be always the main controller in your app.

More info on Tab Bar Controllers can be found at Apple Docs.

Book Index | Next