Available from v4.2.0
TabHeaderViewController
TabHeaderViewController is a parent UIViewController with a brandable header containing multiple child UIViewControllers the user can navigate between either by swiping or by tapping on the child UIViewController's title in the header.
Platform availability: iOS 17.0+
When to use:
- Use TabHeaderViewController when you need a branded header with user information and swipeable navigation between related content sections.
- Consider using NavigationController for hierarchical navigation, or a custom tab implementation for app-level navigation.
Features:
- Brandable header with user information display.
- Avatar with tap action support.
- Trailing view customization for notifications or other controls.
- Swipe and tap navigation between child view controllers.
- Customizable styling for colors, fonts, and backgrounds.
- Support for hiding subtitle and avatar.
- Haptic feedback control.
Import
import BackbaseDesignSystem
Visual reference
|
|
|
API reference
TabHeaderViewController
A container view controller with a branded header and swipeable child navigation.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
design |
TabHeaderViewController.Design! |
The design configuration for styling. |
Initializers
- init(configuration:style:) Initializes a TabHeaderViewController with the given configuration and style.
|
Parameter |
Type |
Description |
|---|---|---|
|
configuration |
Configuration |
The configuration for header and view controllers. |
|
style |
Style<TabHeaderViewController> |
The style to apply. Defaults to DesignSystem.shared.styles.tabHeaderViewController. |
Methods
- selectTabIndex(_:animated:) Selects the tab at the specified index.
|
Parameter |
Type |
Description |
|---|---|---|
|
index |
Int |
The tab index to select. |
|
animated |
Bool |
Whether to animate the selection. Defaults to false. |
TabHeaderViewController.Configuration
|
Property |
Type |
Description |
|---|---|---|
|
header |
Header |
The header configuration. |
|
viewControllers |
[UIViewController] |
The viewControllers array of child view controllers. |
|
extendsIntoSafeArea |
Bool |
The extendsIntoSafeArea flag. Defaults to false. |
|
hapticsEnabled |
Bool |
The hapticsEnabled flag for haptic feedback. Defaults to true. |
|
hideSingleTab |
Bool |
The hideSingleTab flag to hide tab bar with single tab. Defaults to false. |
TabHeaderViewController.Header.UserInformationConfiguration
|
Property |
Type |
Description |
|---|---|---|
|
userPresentable |
TabHeaderViewControllerUserPresentable |
The userPresentable user information to display. |
|
didTapAvatar |
((TabHeaderViewController) -> Void)? |
The didTapAvatar callback for avatar tap action. |
|
trailingView |
UIView? |
The trailingView added to trailing side. |
|
hideSubtitle |
Bool |
The hideSubtitle flag. Defaults to false. |
|
hideAvatar |
Bool |
The hideAvatar flag. Defaults to false. |
TabHeaderViewController.Design
|
Property |
Type |
Description |
|---|---|---|
|
statusBarStyle |
UIStatusBarStyle |
The statusBarStyle for the status bar. |
|
backgroundColor |
UIColor |
The backgroundColor behind child view controllers. |
|
headerBackground |
Background |
The headerBackground (gradient, image, or color). |
|
headerForegroundColor |
UIColor |
The headerForegroundColor for header text. |
|
selectedTabBackgroundColor |
UIColor |
The selectedTabBackgroundColor for selected tabs. |
|
selectedTabTextColor |
UIColor |
The selectedTabTextColor for selected tab text. |
|
deselectedTabTextColor |
UIColor |
The deselectedTabTextColor for deselected tab text. |
|
titleFont |
UIFont |
The titleFont for the header title. |
|
subtitleFont |
UIFont |
The subtitleFont for the header subtitle. |
|
selectedTabTitleFont |
UIFont |
The selectedTabTitleFont for selected tab titles. |
|
deselectedTabTitleFont |
UIFont |
The deselectedTabTitleFont for deselected tab titles. |
TabHeaderViewControllerUserPresentable
A protocol for passing user information to the header.
|
Property |
Type |
Description |
|---|---|---|
|
name |
String |
The name of the user. |
|
company |
String? |
The company of the user (optional). |
|
image |
UIImage? |
The image for the user's avatar (optional). |
Configuration
|
Parameter |
Type |
Default |
|---|---|---|
|
configuration |
Configuration |
Required |
|
style |
Style<TabHeaderViewController> |
DesignSystem.shared.styles.tabHeaderViewController |
configuration
The configuration parameter contains header and view controller settings:
let configuration = TabHeaderViewController.Configuration(
header: header,
viewControllers: [greenViewController, indigoViewController],
extendsIntoSafeArea: false,
hapticsEnabled: true,
hideSingleTab: false
)
style
The style parameter applies visual styling to the tab header view controller:
let customStyle: Style<TabHeaderViewController> = { tabHeaderViewController in
let design = TabHeaderViewController.Design()
design.headerBackground = .color(.systemBlue)
design.headerForegroundColor = .white
tabHeaderViewController.design = design
}
Usage
Step 1: Implement TabHeaderViewControllerUserPresentable
Create a type conforming to the protocol:
struct UserPresentable: TabHeaderViewControllerUserPresentable {
var name: String
var company: String?
var image: UIImage?
}
Step 2: Create the user presentable
let userImage = UIImage(named: "Avatar")
let userPresentable = UserPresentable(name: userName, company: serviceAgreementName, image: userImage)
Step 3: Create the header configuration
Basic configuration:
let headerConfiguration = TabHeaderViewController.Header.UserInformationConfiguration(
userPresentable: userPresentable,
didTapAvatar: { tabHeaderViewController in
print("Avatar Tapped")
},
trailingView: someView
)
Configuration with visibility control:
let headerConfiguration = TabHeaderViewController.Header.UserInformationConfiguration(
userPresentable: userPresentable,
didTapAvatar: { tabHeaderViewController in
print("Avatar Tapped")
},
trailingView: someView,
hideSubtitle: true,
hideAvatar: false
)
Step 4: Create the header
let header: TabHeaderViewController.Header = .userInformation(headerConfiguration)
Step 5: Create child view controllers
let greenViewController = DemoViewController(title: "Green", backgroundColor: .systemGreen)
let indigoViewController = DemoViewController(title: "Indigo", backgroundColor: .systemIndigo)
let orangeViewController = DemoViewController(title: "Orange", backgroundColor: .systemOrange)
Step 6: Create the configuration
let tabHeaderViewControllerConfiguration = TabHeaderViewController.Configuration(
header: header,
viewControllers: [greenViewController, indigoViewController, orangeViewController],
extendsIntoSafeArea: false,
hapticsEnabled: true,
hideSingleTab: false
)
Step 7: Create the TabHeaderViewController
let tabHeaderViewController = TabHeaderViewController(configuration: tabHeaderViewControllerConfiguration)
Hiding single tab
When you have only one tab and want a cleaner interface:
let singleViewController = DemoViewController(title: "Main", backgroundColor: .systemBlue)
let configurationWithHiddenSingleTab = TabHeaderViewController.Configuration(
header: header,
viewControllers: [singleViewController],
hideSingleTab: true
)
Changing default tab
Select a different tab by default:
tabHeaderViewController.selectTabIndex(2)
// Or with animation
tabHeaderViewController.selectTabIndex(2, animated: true)
States and variants
Tab selection states
|
State |
Property |
Description |
|---|---|---|
|
Selected |
selectedTabBackgroundColor |
The currently selected tab |
|
Deselected |
deselectedTabTextColor |
Tabs not currently selected |
Header variants
|
Variant |
Configuration |
Description |
|---|---|---|
|
Full |
All properties set |
Header with avatar, title, subtitle, and trailing view |
|
No subtitle |
hideSubtitle: true |
Header without subtitle text |
|
No avatar |
hideAvatar: true |
Header without user avatar |
// Header without subtitle
let headerConfiguration = TabHeaderViewController.Header.UserInformationConfiguration(
userPresentable: userPresentable,
hideSubtitle: true
)
// Header without avatar
let headerConfiguration = TabHeaderViewController.Header.UserInformationConfiguration(
userPresentable: userPresentable,
hideAvatar: true
)
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.tabHeaderViewController |
Default TabHeaderViewController style. |
Custom styling
Create a custom style:
let tabHeaderViewControllerStyle: Style<TabHeaderViewController> = { tabHeaderViewController in
let tabHeaderViewControllerDesign = TabHeaderViewController.Design()
tabHeaderViewControllerDesign.statusBarStyle = .lightContent
tabHeaderViewControllerDesign.backgroundColor = .white
tabHeaderViewControllerDesign.headerBackground = .color(.systemBlue)
tabHeaderViewControllerDesign.headerForegroundColor = .white
tabHeaderViewControllerDesign.selectedTabBackgroundColor = .white
tabHeaderViewControllerDesign.selectedTabTextColor = .systemBlue
tabHeaderViewControllerDesign.deselectedTabTextColor = .white.withAlphaComponent(0.7)
tabHeaderViewControllerDesign.titleFont = DesignSystem.shared.fonts.preferredFont(.headline, .semibold)
tabHeaderViewControllerDesign.subtitleFont = DesignSystem.shared.fonts.preferredFont(.subheadline, .regular)
tabHeaderViewControllerDesign.selectedTabTitleFont = DesignSystem.shared.fonts.preferredFont(.footnote, .semibold)
tabHeaderViewControllerDesign.deselectedTabTitleFont = DesignSystem.shared.fonts.preferredFont(.footnote, .regular)
tabHeaderViewController.design = tabHeaderViewControllerDesign
}
let tabHeaderViewController = TabHeaderViewController(
configuration: tabHeaderViewControllerConfiguration,
style: tabHeaderViewControllerStyle
)
Accessibility
The TabHeaderViewController has built-in accessibility support for navigation and user information.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
Profile accessibility |
Identifies the profile/avatar area |
String |
|
Menu bar accessibility |
Identifies the tab navigation bar |
String |
|
Tab format |
Format string for tab position announcement |
String |
Best practices
- Each tab announces its title and position (e.g., "Green, 1 of 3")
- Avatar is accessible with the "Profile" label
- Tab navigation supports VoiceOver swipe gestures
Localizable strings
Override these strings to customize accessibility text:
"DesignSystem.tabHeaderViewController.accessibility.profile" = "Profile";
"DesignSystem.tabHeaderViewController.accessibility.separator" = ", "
"DesignSystem.tabHeaderViewController.accessibility.menuBar" = "Menu Bar, ";
"DesignSystem.tabHeaderViewController.accessibility.journeySelectorFormat" = "%@, %d of %d";
Dependencies
- External dependencies: None
- Internal dependencies:
- Avatar: Used for displaying user avatar
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.
Selected state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.tab-header.selected.background |
#FFFFFF |
|
Foreground |
theme.color.tab-header.selected.foreground |
{theme.color.foreground.brand} |
Unselected state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.tab-header.unselected.background |
{theme.color.background.none} |
|
Foreground |
theme.color.tab-header.unselected.foreground |
{theme.color.foreground.support} |
Dimension tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Tab Corner Radius |
theme.radius.tab-header.tab |
8 |
|
Tab Height |
theme.height.tab-header.tab |
32 |
|
Tab Padding X |
theme.padding-x.tab-header.tab |
8 |
|
Tab Padding Y |
theme.padding-y.tab-header.tab |
4 |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Typography |
DesignSystem.shared.fonts.preferredFont(.headline, .semibold) |
Title font |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.subheadline, .regular) |
Subtitle font |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.footnote, .semibold) |
Selected tab title font |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.footnote, .regular) |
Deselected tab title font |
|
Styles |
DesignSystem.shared.styles.tabHeaderViewController |
Default tab header style |
See also
- NavigationController - Navigation controller for embedding
- Avatar - Avatar component used in the header