Available from v1.5.0
TabBarController
TabBarController is a container view controller that manages a multiselection interface, where the selection determines which child view controller to display.
Platform availability: iOS 17.0+
When to use:
- Use TabBarController for app-level navigation where users switch between primary sections of the application.
- Consider using TabHeaderViewController for content-level tab navigation with a branded header.
Features:
- Automatic design system theming.
- Support for tab bar items with titles, icons, and badges.
- Selected and unselected state styling.
- Delegate support for handling tab selection events.
Import
import BackbaseDesignSystem
Visual reference
|
Primary style |
Separator |
API reference
TabBarController
A UITabBarController subclass with automatic design system theming.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
selectedIndex |
Int |
The selectedIndex of the currently selected tab. |
|
viewControllers |
[UIViewController]? |
The viewControllers array of child view controllers. |
|
delegate |
UITabBarControllerDelegate? |
The delegate for handling tab bar events. |
Methods
- setViewControllers(_:animated:) Sets the child view controllers with optional animation.
|
Parameter |
Type |
Description |
|---|---|---|
|
viewControllers |
[UIViewController]? |
The array of view controllers to display. |
|
animated |
Bool |
Whether to animate the transition. |
Configuration
|
Parameter |
Type |
Default |
|---|---|---|
|
selectedIndex |
Int |
0 |
|
viewControllers |
[UIViewController]? |
nil |
selectedIndex
The selectedIndex property controls which tab is currently selected:
let tabBarController = TabBarController()
tabBarController.selectedIndex = 1
// Get the currently selected index
let currentIndex = tabBarController.selectedIndex
viewControllers
The viewControllers property contains the array of child view controllers:
let tabBarController = TabBarController()
let firstViewController = UIViewController()
let secondViewController = UIViewController()
let thirdViewController = UIViewController()
let controllers = [firstViewController, secondViewController, thirdViewController]
tabBarController.viewControllers = controllers
// Add view controllers with animation
tabBarController.setViewControllers(controllers, animated: true)
Usage
Basic usage
Create a TabBarController instance and configure it with child view controllers:
let tabBarController = TabBarController()
let firstViewController = UIViewController()
firstViewController.tabBarItem = UITabBarItem(title: "First", image: UIImage(systemName: "house")!, tag: 0)
let secondViewController = UIViewController()
secondViewController.tabBarItem = UITabBarItem(title: "Second", image: UIImage(systemName: "star")!, tag: 1)
tabBarController.setViewControllers([firstViewController, secondViewController], animated: false)
Advanced usage
Configure multiple tabs with selected images and badges:
let tabBarController = TabBarController()
let homeViewController = UIViewController()
homeViewController.title = "Home"
homeViewController.tabBarItem = UITabBarItem(
title: "Home",
image: UIImage(systemName: "house")!,
selectedImage: UIImage(systemName: "house.fill")!
)
let profileViewController = UIViewController()
profileViewController.title = "Profile"
profileViewController.tabBarItem = UITabBarItem(
title: "Profile",
image: UIImage(systemName: "person")!,
selectedImage: UIImage(systemName: "person.fill")!
)
let settingsViewController = UIViewController()
settingsViewController.title = "Settings"
settingsViewController.tabBarItem = UITabBarItem(
title: "Settings",
image: UIImage(systemName: "gear")!,
selectedImage: UIImage(systemName: "gear.fill")!
)
tabBarController.setViewControllers(
[homeViewController, profileViewController, settingsViewController],
animated: true
)
tabBarController.selectedIndex = 0
Handling tab selection
Implement the delegate to respond to tab changes:
class MyViewController: UIViewController, UITabBarControllerDelegate {
func setupTabBarController() {
let tabBarController = TabBarController()
tabBarController.delegate = self
}
func tabBarController(_ tabBarController: UITabBarController, didSelect viewController: UIViewController) {
print("Tab selected at index: \(tabBarController.selectedIndex)")
}
func tabBarController(_ tabBarController: UITabBarController, shouldSelect viewController: UIViewController) -> Bool {
// Return false to prevent selection
return true
}
}
States and variants
Tab selection states
|
State |
Property |
Description |
|---|---|---|
|
Selected |
selectedIndex |
The currently active tab |
|
Normal |
- |
Tabs not currently selected |
Tab bar item states
|
State |
Configuration |
Description |
|---|---|---|
|
Normal |
image |
Default icon appearance |
|
Selected |
selectedImage |
Icon when tab is selected |
|
Badge |
badgeValue |
Notification badge on tab |
// Configure tab bar item states
let viewController = UIViewController()
let tabBarItem = UITabBarItem(
title: "Home",
image: UIImage(systemName: "house")!,
selectedImage: UIImage(systemName: "house.fill")!
)
viewController.tabBarItem = tabBarItem
// Add badge
tabBarItem.badgeValue = "3"
tabBarItem.badgeColor = .systemRed
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.tabBarStyle |
Default tab bar style applied automatically. |
Custom styling
The tab bar appearance uses TabBarTokens for customization:
let customTokens = TabBarTokens(
backgroundColor: .systemBackground,
selectedTitleColor: .systemBlue,
selectedIconColor: .systemBlue,
unselectedTitleColor: .systemGray,
unselectedIconColor: .systemGray,
lineColor: .separator
)
tabBarController.tabBar.setup(tokens: customTokens)
Events
|
Event |
Type |
Description |
|---|---|---|
|
delegate |
UITabBarControllerDelegate? |
Delegate for handling tab bar controller events. |
Accessibility
The TabBarController inherits UITabBarController accessibility with automatic tab navigation support.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
Label for the tab bar controller |
String? |
|
tabBarItem.accessibilityLabel |
Label for individual tab items |
String? |
|
tabBarItem.accessibilityHint |
Hint for individual tab items |
String? |
Best practices
- Each tab bar item should have a meaningful accessibilityLabel that describes its purpose
- Badge values are automatically announced by screen readers
- Tab selection changes are communicated through accessibility notifications
let homeViewController = UIViewController()
homeViewController.tabBarItem = UITabBarItem(title: "Home", image: UIImage(systemName: "house")!, tag: 0)
homeViewController.tabBarItem.accessibilityLabel = "Home tab"
homeViewController.tabBarItem.accessibilityHint = "Navigate to home screen"
Dependencies
- External dependencies: None
- Internal dependencies: None
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Color tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.tab-bar.background |
{theme.color.background.surface-1} |
|
Default Title |
theme.color.tab-bar.menu-item.default.title |
{theme.color.foreground.support} |
|
Default Icon |
theme.color.tab-bar.menu-item.default.icon |
{theme.color.foreground.support} |
|
Active Title |
theme.color.tab-bar.menu-item.active.title |
{theme.color.foreground.brand} |
|
Active Icon |
theme.color.tab-bar.menu-item.active.icon |
{theme.color.foreground.brand} |
Semantic tokens
Tab bar colors are configured via the JSON tokens above. The following tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Background |
theme.color.tab-bar.background |
Tab bar background (from JSON) |
|
Default Title |
theme.color.tab-bar.menu-item.default.title |
Inactive tab text color (from JSON) |
|
Active Title |
theme.color.tab-bar.menu-item.active.title |
Active tab text color (from JSON) |
|
Typography |
DesignSystem.shared.fonts.defaultFont(.caption2, .regular) |
Tab text font |
|
Styles |
DesignSystem.shared.styles.tabBarStyle |
Default tab bar style |
See also
- TabHeaderViewController - Content-level tab navigation with branded header
- NavigationController - Hierarchical navigation controller