NavigationController
NavigationController is a themed subclass of UINavigationController that integrates with the Backbase Design System for consistent styling of navigation bars, buttons, and search controllers.
Platform availability: iOS 17.0+
When to use:
- Use NavigationController when building navigation hierarchies that require consistent theming with the design system.
- Consider custom implementation only when you need completely custom navigation styling outside the design system.
It includes the following features:
- Automatic styling of back buttons.
- Factory methods for creating styled bar button items.
- Integration with design system themes.
- Support for custom status bar styles.
- Built-in search controller styling.
- Background customization with solid color, gradient, or image.
Import
import BackbaseDesignSystem
Visual reference
default Nav Bar
|
Gradient Nav Bar
|
Icon Nav Bar |
Image Nav Bar |
Modal Nav Bar
|
Modal Page Nav Bar
|
API reference
NavigationController
Properties
|
Property |
Type |
Description |
|---|---|---|
|
backButtonStyle |
Style<UIBarButtonItem> |
The style for back/close buttons. Applied automatically |
|
iconButtonStyle |
Style<UIBarButtonItem> |
The style for icon-based bar button items |
|
searchBarStyle |
Style<UISearchBar> |
The style for search bars added to this navigation controller |
|
statusBarStyle |
UIStatusBarStyle |
The preferred status bar style. Defaults to .default |
|
textButtonStyle |
Style<UIBarButtonItem> |
The style for text-based bar button items |
Initializers
|
Initializer |
Description |
|---|---|
|
init() |
Creates with default style, no root view controller |
|
init(rootViewController: UIViewController) |
Creates with root view controller using default style |
|
init(rootViewController: UIViewController, style: Style<NavigationController>) |
Creates with root view controller and custom style |
|
init(style: Style<NavigationController>) |
Creates with custom style, no root view controller |
Methods
- createBarButtonItem(icon:action:)
- Creates a styled icon bar button item.
|
Parameter |
Type |
Description |
|---|---|---|
|
icon |
UIImage |
The icon image for the button |
|
action |
(UIBarButtonItem) -> Void |
The action closure called when tapped |
Returns: UIBarButtonItem - A styled bar button item
- createBarButtonItem(icon:style:buttonType:action:)
- Creates a fully customizable icon bar button item.
|
Parameter |
Type |
Description |
|---|---|---|
|
icon |
UIImage |
The icon image for the button |
|
style |
Style<UIBarButtonItem>? |
Optional custom style |
|
buttonType |
BarButtonType |
The button type (.brand or .danger) |
|
action |
(UIBarButtonItem) -> Void |
The action closure called when tapped |
Returns: UIBarButtonItem - A styled bar button item
- createBarButtonItem(text:action:)
- Creates a styled text bar button item.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String |
The text label for the button |
|
action |
(UIBarButtonItem) -> Void |
The action closure called when tapped |
Returns: UIBarButtonItem - A styled bar button item
- createBarButtonItem(text:style:buttonType:action:)
- Creates a fully customizable text bar button item.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String |
The text label for the button |
|
style |
Style<UIBarButtonItem>? |
Optional custom style |
|
buttonType |
BarButtonType |
The button type (.brand or .danger) |
|
action |
(UIBarButtonItem) -> Void |
The action closure called when tapped |
Returns: UIBarButtonItem - A styled bar button item
- createCloseButton(action:)
- Creates a styled close button for modal presentations.
|
Parameter |
Type |
Description |
|---|---|---|
|
action |
(UIBarButtonItem) -> Void |
The action closure called when tapped |
Returns: UIBarButtonItem - A styled close button
- createSearchController()
- Creates a styled search controller without results controller.
- Returns: UISearchController - A styled search controller
- createSearchController(searchResultsController:)
- Creates a styled search controller with a results controller.
|
Parameter |
Type |
Description |
|---|---|---|
|
searchResultsController |
UIViewController? |
The view controller for displaying results |
Returns: UISearchController - A styled search controller
NavigationControllerTokens
|
Property |
Type |
Description |
|---|---|---|
|
actionsColor |
UIColor |
The tint color for icon-based bar button items |
|
actionsTextColor |
UIColor |
The tint color for text-based bar button items |
|
backIcon |
UIImage? |
The custom back button icon |
|
background |
NavigationController.Background |
The background style (color, gradient, or image) |
|
isTranslucent |
Bool |
Whether the navigation bar is translucent |
|
textColor |
UIColor |
The color for navigation bar title text |
|
underlineColor |
UIColor? |
The color of the separator line below the bar |
BarButtonType Enum
|
Case |
Description |
|---|---|
|
brand |
Standard button with brand coloring |
|
danger |
Destructive action button with warning coloring |
Usage
Basic usage
let navigationVC = NavigationController(rootViewController: MyViewController())
With custom style
let navigationVC = NavigationController(
rootViewController: MyViewController(),
style: DesignSystem.shared.styles.modalNavigationController
)
Creating bar button items
guard let navigationController = navigationController as? NavigationController else { return }
let closeButton = navigationController.createCloseButton { _ in
self.dismiss(animated: true)
}
navigationItem.leftBarButtonItem = closeButton
let iconButton = navigationController.createBarButtonItem(
icon: DesignSystem.Assets.icAdd
) { _ in
// Handle action
}
navigationItem.rightBarButtonItem = iconButton
Using search controller
guard let navigationController = navigationController as? NavigationController else { return }
let resultsController = SearchableTableViewController()
let searchController = navigationController.createSearchController(searchResultsController: resultsController)
searchController.searchBar.delegate = self
navigationItem.searchController = searchController
navigationItem.hidesSearchBarWhenScrolling = false
Icon as title
viewController.addImageToNavigationItemTitleView(
DesignSystem.Assets.icUnionPay,
withHeight: 30
)
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.modalNavigationController |
Style for modal presentations |
|
DesignSystem.shared.styles.navigationController |
Default style for push navigation |
Custom style with tokens
let underlinedNavStyle: Style<UINavigationController> = { nav in
nav.setup(tokens:
NavigationControllerTokens(
background: .color(UIColor.black),
textColor: UIColor(light: .black, dark: .systemBlue),
actionsColor: UIColor(light: .systemPurple, dark: .systemYellow),
isTranslucent: false,
underlineColor: UIColor.systemGreen
)
)
}
DesignSystem.shared.styles.navigationController = underlinedNavStyle
Gradient background
let gradientNavStyle: Style<UINavigationController> = { nav in
let gradient = DesignSystem.Gradient(
startPoint: DesignSystem.Gradient.Point(
point: .init(x: 0.5, y: 0),
color: Theme.colors.background.brand
),
endPoint: DesignSystem.Gradient.Point(
point: .init(x: 0.5, y: 1),
color: Theme.colors.background.brandPressed
)
)
nav.setup(tokens:
NavigationControllerTokens(
background: .gradient(gradient),
textColor: UIColor(light: .white, dark: .systemBlue),
actionsColor: UIColor(light: .systemYellow, dark: .systemPurple),
isTranslucent: false
)
)
}
Image background
let imageNavStyle: Style<UINavigationController> = { nav in
nav.setup(tokens:
NavigationControllerTokens(
background: .image(UIImage.named("Test", in: nil)!),
textColor: UIColor(light: .white, dark: .black),
actionsColor: UIColor(light: .white, dark: .black),
isTranslucent: false
)
)
}
Accessibility
This component is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
The accessible label for back buttons (automatically configured) |
String |
|
accessibilityTraits |
The accessibility traits for bar button items |
UIAccessibilityTraits |
Best practices
- Back buttons are automatically configured with accessibility labels.
- Close buttons include appropriate accessibility labels.
- Bar button items support VoiceOver navigation.
- Use descriptive text for custom bar button items to improve screen reader experience.
let actionButton = navigationController.createBarButtonItem(
icon: DesignSystem.Assets.icSettings
) { _ in
// Handle action
}
actionButton.accessibilityLabel = "Settings"
navigationItem.rightBarButtonItem = actionButton
Dependencies
- External dependencies: None
- Internal dependencies: SearchController
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses semantic tokens only. See Semantic tokens below.
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.background.brand |
Brand background for gradient styles |
|
Colors |
Theme.colors.background.default |
Navigation bar background color |
|
Colors |
Theme.colors.foreground.default |
Title and icon color |
|
Styles |
DesignSystem.shared.styles.modalNavigationController |
Modal presentation style |
|
Styles |
DesignSystem.shared.styles.navigationController |
Default navigation controller style |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.headline, .semibold) |
Navigation bar title font |
Localization
Override the following strings to customize text for the NavigationController:
"DesignSystem.navigationController.backButtonTitle" = "Back";
See also
- SearchController - Styled search controller component