Navigational controls displayed in a bar along the top of the screen, usually in conjunction with a navigation controller.
- iOS 2.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
UINavigation object is a bar, typically displayed at the top of the window, containing buttons for navigating within a hierarchy of screens. The primary components are a left (back) button, a center title, and an optional right button. You can use a navigation bar as a standalone object or in conjunction with a navigation controller object.
A navigation bar is most commonly used within a navigation controller. The
UINavigation object creates, displays, and manages its associated navigation bar, and uses attributes of the view controllers you add to control the content displayed in the navigation bar.
To control a navigation bar when using a navigation controller, the following steps are required:
Create a navigation controller in Interface Builder or in the code.
You can also use a standalone navigation bar, without using a navigation controller. To add a navigation bar to your interface, the following steps are required:
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 user interactions with the navigation bar.
Customize the appearance of the navigation bar.
Configure your app to push and pop relevant navigation items as the user navigates through the hierarchical screens.
Using a Navigation Bar with a Navigation Controller
If you use a navigation controller to manage the navigation between different screens of content, the navigation controller creates a navigation bar automatically and pushes and pops navigation items when appropriate.
A navigation controller uses the
navigation property on
UIView to provide the model objects to its navigation bar when navigating a stack of view controllers. The default navigation item uses the view controller’s title, but you can override the
navigation on a
UIView subclass to gain complete control of the navigation bar’s content.
A navigation controller automatically assigns itself as the delegate of its navigation bar object. Therefore, when using a navigation controller, don’t assign a custom delegate object to the corresponding navigation bar.
To access the navigation bar associated with a navigation controller, use the
navigation property on
UINavigation. See Customizing the Appearance of a Navigation Bar for details on how to customize the appearance of a navigation bar.
For information about navigation controllers, see
Adding Content to a Standalone Navigation Bar
In the vast majority of scenarios you will use a navigation bar as part of a navigation controller. However, there are situations for which you might want to use the navigation bar UI and implement your own approach to content navigation. In these situations, you can use a standalone navigation bar.
When you use a navigation bar as a standalone object, you are responsible for providing its content. Unlike other types of views, you do not add subviews to a navigation bar directly. Instead, you use a navigation item (an instance of the
UINavigation class) to specify what buttons or custom views you want displayed. A navigation item has properties for specifying views on the left, right, and center of the navigation bar and for specifying a custom prompt string. Figure 1 shows how the navigation item properties manifest themselves in a navigation bar.
A navigation bar manages a stack of
UINavigation objects. Although the stack is there mostly to support navigation controllers, you can use it to implement your own custom navigation interface. The topmost item in the stack represents the navigation item whose contents are currently displayed by the navigation bar. You push new navigation items onto the stack using the
push method and pop items off the stack using the
pop method. Both of these changes can be animated for the benefit of the user.
In addition to pushing and popping items, you can also set the contents of the stack directly using either the
items property or the
set method. You might use this method at launch time to restore your interface to its previous state or to push or pop more than one navigation item at a time.Figure 2 shows the part of the
UINavigation API responsible for managing the stack of navigation items.
If you are 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
UINavigation protocol. The delegate notifications let you track when navigation items are pushed or popped from the stack. You use these notifications to update the rest of your app’s user interface.
Customizing the Appearance of a Navigation Bar
Navigation bars have two standard appearance styles: white with dark text or black with light text. Use the
bar property to select the style. Any changes you make to other navigation bar appearance properties override those inferred from the bar style.
Navigation bars are translucent by default; that is, their background color is semitransparent. You can make the navigation bar opaque by setting the
is property to
You can specify a custom tint color for a navigation bar background using the
bar property. Setting this property overrides the default color inferred from the bar style. As with all
UIView subclasses, you can control the color of the interactive elements within navigation bars, including button images and titles, using the
title property specifies the attributes for displaying the bar’s title text. You can specify the font, text color, text shadow color, and text shadow offset for the title in the text attributes dictionary using the
shadow keys, respectively. For more information about string-formatting attributes, see Character Attributes.
set method to adjust the vertical position of the title. This method allows you to specify the adjustment dependent on the bar height, which is represented by the
UIBar enum.Figure 3 shows a navigation bar with custom tint color, title text attributes and bar tint color.
To allow complete customization over the appearance of navigation bars, you can additionally provide custom background and shadow images. To provide a custom background image, use the
set method, providing a
UIImage object for the appropriate bar position and metrics values. Use a
UIBar value for the bar position argument to specify whether to use the supplied image at the bottom or the top of the window, and if it appears at the top, whether to extend it upward under the status bar. Similarly, you can specify that the image should be used for either compact or default bar metrics, with or without a prompt, by providing a
UIBar value to the bar metrics argument.
To add a shadow, provide a resizable
UIImage to the
shadow property. To use the custom shadow image, you need to have specified a custom background image. Figure 4 shows a navigation bar with a custom background image, supplied using
set with a bar position value of
UIBar and a bar metrics value of
UIBar. A custom image has also been provided to the
To see examples of customizing a navigation bar, see Customizing Your App’s Navigation Bar.
Interface Builder Attributes
Table 1 lists the core attributes that you configure for navigations bars in the Attributes Inspector within Interface Builder.
Specifies the UI bar style to apply to the navigation bar. The bar style controls the title color and the bar tint color, but you can override it by providing values for those attributes. Select Translucent to make the navigation bar semitransparent. Access these values at runtime with the
Controls the tint color of the navigation bar. This overrides the value implied by the Style attribute. If the Translucent attribute is selected, the Bar Tint color is automatically made semitransparent. Access this value at runtime with the
Represents the image used as a shadow beneath the navigation bar. This image is stretched horizontally to match the width of the bar. Access this value at runtime with the
Specifies the image that appears at the leading edge of the back button. This attribute must be used in combination with the Back Mask attribute. Access this value at runtime with the
Specifies the mask associated with the Back Image attribute. This is used to control the appearance of the Back button during animated transitions, and therefore must be used in conjunction with the Back Image attribute. Access this value at runtime with the
Table 2 lists the Interface Builder attributes that affect the appearance of the navigation bar’s title.
Specifies the color and offset of the shadow used when rendering the navigation bar’s title. Access these values at runtime with the dictionary in the [
To internationalize navigation bars, specify a localized string for each of the displayed string properties of the navigation item model objects.
For more information about internationalizing your interface, see Internationalization and Localization Guide.
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, after the user navigates to a new view in the hierarchy, VoiceOver reads the navigation bar’s title, followed by the name of the left bar button item. When the user taps an element in a navigation bar, VoiceOver reads the name and the type of the element; for example, "General back button," "Keyboard heading," and "Edit button."
For general information about making your interface accessible, see Accessibility Programming Guide for iOS.