Class

UINavigationBar

Navigational controls displayed in a bar along the top of the screen, usually in conjunction with a navigation controller.

Declaration

class UINavigationBar : UIView

Overview

A UINavigationBar 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 UINavigationController 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.
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.

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 navigationItem property on UIViewController 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 navigationItem on a UIViewController 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 navigationBar property on UINavigationController. 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 UINavigationController.

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 UINavigationItem 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 UINavigationItem 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 pushItem(_:animated:) method and pop items off the stack using the popItem(animated:) 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 setItems(_:animated:) 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 UINavigationBar API responsible for managing the stack of navigation items.

**Figure 2**
Navigation bar stack management

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 UINavigationBarDelegate 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.

For more information about creating navigation items, see UINavigationItem. For more information about implementing a delegate object, see UINavigationBarDelegate.

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 barStyle 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 isTranslucent property to false.

You can specify a custom tint color for a navigation bar background using the barTintColor 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 tintColor property.

The titleTextAttributes 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 font, foregroundColor, and shadow keys, respectively. For more information about string-formatting attributes, see Character Attributes.

Use the setTitleVerticalPositionAdjustment(_:for:) 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 UIBarMetrics enum.Figure 3 shows a navigation bar with custom tint color, title text attributes and bar tint color.

**Figure 3**
Navigation bar fonts and colors

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 setBackgroundImage(_:for:barMetrics:) method, providing a UIImage object for the appropriate bar position and metrics values. Use a UIBarPosition 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 UIBarMetrics value to the bar metrics argument.

To add a shadow, provide a resizable UIImage to the shadowImage 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 setBackgroundImage(_:for:barMetrics:) with a bar position value of UIBarPosition.topAttached and a bar metrics value of UIBarMetrics.default. A custom image has also been provided to the shadowImage property.

**Figure 4**
Navigation bar with custom background and shadow images

Interface Builder Attributes

Table 1 lists the core attributes that you configure for navigations bars in the Attributes Inspector within Interface Builder.

Table 1

Core Attributes

Attribute	Description
Style	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 `barStyle` and `isTranslucent` properties.
Bar Tint	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 `barTintColor` property.
Shadow Image	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 `shadowImage` property.
Back Image	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 `backIndicatorImage` property.
Back Mask	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 `backIndicatorTransitionMaskImage` property.

Table 2 lists the Interface Builder attributes that affect the appearance of the navigation bar’s title.

Table 2

Title attributes

Attribute	Description
Title Font	The font used to render the title in the center of the navigation bar. Access this value at runtime with the value stored against the `font` key in the dictionary in the `titleTextAttributes` property.
Title Color	The color used to render the navigation bar title. Access this value at runtime using the `foregroundColor` key in the dictionary in the `titleTextAttributes` property.
Title Shadow	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 [`titleTextAttributes`] property, using the `shadow` key.

Internationalization

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.

Accessibility

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.

Topics

Responding to Navigation Bar Changes

var delegate: UINavigationBarDelegate?

The navigation bar’s delegate object.

protocol UINavigationBarDelegate

The UINavigationBarDelegate protocol defines optional methods that a UINavigationBar delegate should implement to update its views when items are pushed and popped from the stack. The navigation bar represents only the bar at the top of the screen, not the view below. It’s the application’s responsibility to implement the behavior when the top item changes.