UINavigationBar
A region that displays the title and controls provided by navigation items.
Declaration
@MainActor class UINavigationBarMentioned in
Overview
The primary components of a UINavigationBar are its title, subtitle, and leading and trailing items. Use UINavigationBar with UINavigationController whenever possible. The navigation controller creates, displays, and manages its associated navigation bar, and uses attributes of the view controllers in its navigation stack to control the content displayed in the navigation bar. You create a navigation bar directly only when you use a standalone navigation bar, and you handle its events with a UINavigationBarDelegate object.
[Image]
To use a navigation bar with a navigation controller:
Create a navigation controller in Interface Builder or in code.
Configure the appearance of the navigation bar using the navigationBar property on the UINavigationController object.
Control the content of the navigation bar by setting the title and navigationItem properties on each UIViewController you push onto the navigation controller’s stack.
A navigation controller also handles layout changes for you. On iPhone Duo, the system places each item from your UINavigationItem along either the horizontal axis at the top of the screen or the vertical axis along the side. The navigation bar content can appear along one axis or be divided between both.
The system also updates the safe area so your content avoids the navigation controls. Use standard system components to get this behavior automatically.
To add a navigation bar to your interface without using a navigation controller:
Set up Auto Layout rules to govern the position of the navigation bar in your interface.
Create a root navigation item to supply the initial title.
Configure a delegate object to handle interactions with the navigation bar.
Customize the appearance of the navigation bar.
Configure your app to push and pop relevant navigation items as people navigate through the hierarchical screens.
Use a navigation bar with a navigation controller
If you use a navigation controller to manage the navigation between view controllers, the navigation controller creates a navigation bar automatically and pushes and pops navigation items when appropriate.
A navigation controller automatically assigns itself as the delegate of its navigation bar object. Don’t assign a custom delegate.
To access the navigation bar associated with a navigation controller, use the navigationBar property on UINavigationController. For details on appearance customization, see “Customize the appearance of a navigation bar,” below.
For more information about navigation controllers, see UINavigationController.
Add content to a standalone navigation bar
Most apps use a navigation bar as part of a navigation controller. If you want the navigation bar user interface but need your own approach to content navigation, consider a standalone navigation bar.
When you use a navigation bar as a standalone object, you’re responsible for providing its content. Unlike other types of views, you don’t add subviews to a navigation bar directly. Instead, you use a navigation item (an instance of the UINavigationItem class) to specify the buttons or custom views to display. A navigation item provides properties for configuring its title, its subtitle, and its leading, center, and trailing bar items.
Navigation bars manage a stack of UINavigationItem objects. Although the stack is there mostly to support navigation controllers, you can use it to implement a custom navigation interface. The topmost item in the stack represents the navigation item whose contents are available in the navigation bar. You push new navigation items onto the stack using the pushItem(_:animated:) method and pop items off the stack using the popItem(animated:) method.
In addition to pushing and popping items, you can also set the contents of the stack directly using either the items property or the setItems(_:animated:) method. You might use this method to apply restored state at launch, or to push or pop more than one navigation item at a time. The following figure shows the part of the UINavigationBar API responsible for managing the stack of navigation items:
[Image]
If you’re using a navigation bar as a standalone object, assign a custom delegate object to the delegate property and use that object to intercept messages coming from the navigation bar. Delegate objects must conform to the UINavigationBarDelegate protocol. Use the delegate to track when the navigation bar pushes or pops navigation items, and update the rest of your app’s user interface in response.
For more information about creating navigation items, see UINavigationItem. To implement a delegate object, see UINavigationBarDelegate.
Customize the appearance of a navigation bar
Navigation bars are transparent and feature bar button items constructed with Liquid Glass. Don’t add a background or apply a tint color to the navigation bar, as that may interfere with the Liquid Glass presentation.
Customize the color of the text or image in a bar button item by setting the tintColor property. To customize the background color of a bar button item, set the bar button’s tint color, then set the bar button’s style property to the value UIBarButtonItem.Style.prominent.
For design guidance, see Human Interface Guidelines > Foundations > Color > Liquid Glass color.
The titleTextAttributes property specifies the attributes for displaying the bar’s title text. Use the following keys in the text attributes dictionary to customize the title bar’s text:
Key | Value | Description |
|---|---|---|
The font to use. | ||
The font color to use. | ||
The shadow object defining, offset, color, and radius to use. |
Use the setTitleVerticalPositionAdjustment(_:for:) method to adjust the vertical position of the title for a given bar height, which the UIBarMetrics enumeration specifies.
For details on appearance customization, see Customize the appearance of a navigation bar.
Customize a navigation bar with Interface Builder
The following table lists the Interface Builder attributes that affect the appearance of the navigation bar’s title.
Key | Attribute | Description |
|---|---|---|
Title Font | The font to use. | |
Title Color | The font color to use. | |
Title Shadow | The shadow object defining, offset, color, and radius to use. |
Localize a navigation bar
To localize navigation bars, specify a localized string for each of the displayed string properties of the navigation item model objects.
For more information about localizing your interface, see Localization.
Make a navigation bar accessible
Navigation bars are accessible by default. The default accessibility trait for a navigation bar is User Interaction Enabled.
With VoiceOver enabled on an iOS device, when someone focuses on the back button in a navigation bar, VoiceOver reads the title of the previous view followed by the element type, for example, “General, back button.” When someone focuses on other elements in a navigation bar, VoiceOver reads the name and type of the element, for example, “Keyboard, heading” and “Edit, button.”
For information on how to make your interface accessible, see Accessibility for UIKit.
Build your app with Mac Catalyst
When you build your app with Mac Catalyst and it runs with the UIUserInterfaceIdiom.mac, the system can display a navigation bar’s content in an NSToolbar instead of displaying the navigation bar directly. This is the default behavior when preferredBehavioralStyle is UIBehavioralStyle.automatic. Setting preferredBehavioralStyle to UIBehavioralStyle.mac doesn’t change this behavior on the Mac idiom, and the system ignores this setting when your app runs with the UIUserInterfaceIdiom.pad. To opt out of this behavior, set preferredBehavioralStyle to UIBehavioralStyle.pad.
To choose which section of the toolbar displays the navigation bar, implement navigationBarNSToolbarSection(_:) on the navigation bar’s delegate. If you use UINavigationController to manage your navigation bar, you typically don’t need to implement this method yourself, because UINavigationController already implements it as the navigation bar’s delegate.
Not every navigation item property is supported in every toolbar section. For more information, see Display content in a toolbar on Mac.
Topics
Responding to navigation bar changes
Pushing and popping items
Customizing the bar’s appearance
prefersLargeTitlesstandardAppearancecompactAppearancescrollEdgeAppearancecompactScrollEdgeAppearanceisTranslucentLegacy customizations