skip to content

In UIKit, how should a UITabBarController hold Home, Orders and Account tabs so that each tab keeps its own navigation stack?

level: middleimportance: must knowfreq 68%

answer

  1. which container wraps which
  2. the tab bar controller sits at the root
  3. one UINavigationController per tab
  4. hidesBottomBarWhenPushed on the pushed screen
  5. UITab and init(tabs:) since iOS 18

basics

~20 s

Give each tab its own UINavigationController as its root and keep the UITabBarController outside every navigation stack. Each tab then pushes and pops independently; iOS 18 adds UITab objects as another way to declare tabs.

solid answer

~40 s

The `UITabBarController` is the outer container and each tab's root view controller is its own `UINavigationController`, set through `viewControllers` with a `tabBarItem` on each navigation controller. Because every tab owns a separate stack, switching from Orders to Home and back leaves Orders exactly where the user left it. The reverse nesting fails: a navigation controller has one stack, and `pushViewController(_:animated:)` can't push a tab bar controller. To hide the tab bar on a detail screen, set `hidesBottomBarWhenPushed = true` on the screen being pushed, before the push. The delegate's `tabBarController(_:shouldSelect:)` can refuse a tab, for example Account while signed out. From iOS 18 you can also build tabs as `UITab` objects passed to `init(tabs:)`; each tab's `viewControllerProvider` creates its root when UIKit first asks for it.

code

swift · 27 lines
swift
import UIKit

@MainActor
func makeRootTabs(home: UIViewController,
                  orders: UIViewController,
                  account: UIViewController) -> UITabBarController {
    func stack(_ root: UIViewController, _ title: String, _ symbol: String) -> UINavigationController {
        let nav = UINavigationController(rootViewController: root)
        nav.tabBarItem = UITabBarItem(title: title, image: UIImage(systemName: symbol), tag: 0)
        return nav
    }
    let tabs = UITabBarController()
    tabs.viewControllers = [
        stack(home, "Home", "house"),
        stack(orders, "Orders", "bag"),
        stack(account, "Account", "person"),
    ]
    return tabs
}

final class DishViewController: UIViewController {
    init() {
        super.init(nibName: nil, bundle: nil)
        hidesBottomBarWhenPushed = true // the tab bar slides out while this screen is on top
    }
    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
}

go deeper

for a junior

Recall the nesting: tab bar controller at the root, a navigation controller inside each tab, and a tabBarItem on each navigation controller.

for a middle

Explain why the reverse nesting breaks, where hidesBottomBarWhenPushed goes, and how the delegate can refuse a tab before it opens.

for a senior

Handle runtime tab changes and the More controller, gate a tab behind sign-in, and adopt UITab behind an availability check without forking the app's structure.

for a principal

Weigh moving to the iOS 18 tab API for sidebar and customization against the deployment target, and set one rule for which object builds and owns each tab's stack.

## Why each tab needs its own stack A **`UITabBarController`** shows one of several **root view controllers** at a time and lets the user switch between them with the tab bar. A **`UINavigationController`** keeps one **navigation stack**, an ordered list of screens with Back navigation. In a food-delivery app, Home drills from restaurants to a menu to a dish, Orders drills from the order list to one order's tracking screen, and Account drills into settings. Users expect to leave a half-finished drill in Home, check an order, and come back to Home exactly where they were. That falls out of one arrangement: **the tab bar controller outside, one navigation controller inside each tab.** | Nesting | Result | |---|---| | tab bar controller → one navigation controller per tab | every tab keeps its own history; the tab bar stays visible while you drill in | | one navigation controller → tab bar controller | one shared history; and `pushViewController(_:animated:)` documents that the pushed object can't be a tab bar controller | | one navigation controller reused in several tabs | impossible: a view controller has a single parent container | ## Building it with viewControllers 1. Create each tab's first screen. 2. Wrap each in `UINavigationController(rootViewController:)`. 3. Give each navigation controller a `tabBarItem` (title and image), because the tab bar reads the item from the tab's root, which is the navigation controller. 4. Assign the array to `viewControllers`; the order is the order of the tabs. Pick the starting tab with `selectedIndex` or `selectedViewController`. If you replace `viewControllers` at runtime, the tab bar controller removes the old children, tries to reselect the previously selected one, falls back to the same index, and finally to index 0. If there are more tabs than fit, the extra ones go into the system **More** navigation controller, which is not part of `viewControllers`. ## Building it with UITab (iOS 18) From **iOS 18** you can describe tabs as **`UITab`** objects and pass them to `UITabBarController(tabs:)`. Each `UITab` has a title, an image, a stable `identifier` and a `viewControllerProvider` closure. UIKit calls the closure when it needs the tab's view controller and doesn't have one yet; for root tabs it must return a view controller. The provider still returns a `UINavigationController` for each tab, so the one-stack-per-tab rule doesn't change. The same API powers iPad's sidebar and tab customization. An app deploying to iOS 17 keeps the `viewControllers` path or branches with `if #available(iOS 18.0, *)`. ## Hiding the tab bar on a pushed screen A dish detail screen often wants the whole height. Set **`hidesBottomBarWhenPushed`** to `true` on the view controller **being pushed**, before you push it; the tab bar slides out when that screen is pushed into the tab's stack. Setting it on the screen underneath does nothing for this push. `isToolbarHidden` and `hidesBarsOnSwipe` belong to the navigation controller's own bars, not to the tab bar. ## What the tab bar controller adjusts for you When a tab's root is a navigation controller, the tab bar controller adjusts the size of the navigation content so it doesn't overlap the tab bar, so screens lay out against their safe area instead of guessing the bar's height. From iOS 18 the tab bar controller itself also has `isTabBarHidden` and `setTabBarHidden(_:animated:)`, which hide the bar for the whole controller; `hidesBottomBarWhenPushed` remains the per-screen tool for one pushed screen. For state restoration, give each tab's child a unique restoration identifier: a tab without one returns to its default configuration on the next launch. ## Reacting to tab selection The **`UITabBarControllerDelegate`** receives the selection events: - `tabBarController(_:shouldSelect:)` returns `false` to refuse a tab, for example to present sign-in before Account opens. - `tabBarController(_:didSelect:)` runs after the selection changes. - With the iOS 18 tab API, `tabBarController(_:shouldSelectTab:)` and `tabBarController(_:didSelectTab:previousTab:)` are the equivalents. ## Mistakes reviewers catch - Wrapping the whole tab bar controller in a navigation controller, so every tab shares one history. - Setting `hidesBottomBarWhenPushed` on the wrong screen, or after the push has started. - Calling `UITab` APIs on an iOS 17 deployment target without an availability check. - Reaching into `tabBar` to edit its items directly instead of setting each child's `tabBarItem`.

  • How do you stop a signed-out user from opening the Account tab?
    Make an object the tab bar controller's delegate and return false from tabBarController(_:shouldSelect:) when the Account tab is chosen while signed out, presenting the sign-in screen instead. With the iOS 18 tab API the matching method is tabBarController(_:shouldSelectTab:). The tab bar never switches, so the user keeps their current tab underneath sign-in.
  • What happens to the selected tab when you replace viewControllers at runtime?
    The tab bar controller removes all the old children and installs the new ones without animating the items. It then tries to reselect the previously selected view controller; if that object is gone it selects the same index, and if the index is out of range it selects index 0.

  • Wraps the UITabBarController in one UINavigationController so all tabs share a stack.
  • Reuses a single UINavigationController instance in several tabs.
  • Sets hidesBottomBarWhenPushed on the screen underneath instead of the pushed screen.
  • Assumes UITab and init(tabs:) work on an iOS 17 deployment target.
  • Edits the tabBar's items directly instead of each child's tabBarItem.

Assumes the iOS 27.1 SDK; UITab, init(tabs:) and the tabs property arrived in iOS 18, while viewControllers works on every supported release.