iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UINavigationBar Class Reference

Options
Deployment Target:

On This Page
Language:

UINavigationBar

The UINavigationBar class provides a control for navigating hierarchical content. It’s a bar, typically displayed at the top of the screen, containing buttons for navigating within a hierarchy of screens. The primary properties 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.

Using a Navigation Bar With a Navigation Controller

The most common way to use a navigation bar is in conjunction with a UINavigationController object. If you use a navigation controller to manage the navigation between different screens of content, the navigation controller creates the 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. Therefore, when using a navigation controller, don’t assign a custom delegate object to the corresponding navigation bar.

For information about navigation controllers, see UINavigationController Class Reference.

Customizing the Appearance of a Navigation Bar

In iOS 5.0 and later, you can customize the appearance of the bar using the methods listed in Customizing the Bar Appearance. You can customize the appearance of all navigation bars using the appearance proxy ([UINavigationBar appearance]), or just of a single bar.

In iOS 7, a navigation bar’s tintColor affects the color of the back indicator image, button titles, and button images. The barTintColor property affects the color of the bar itself. Additionally, navigation bars are translucent by default. Turning the translucency off or on does not affect buttons, since they do not have backgrounds.

In general, when a property is dependent on the bar metrics (on the iPhone in landscape orientation, bars have a different height from standard), be sure to specify a value for UIBarMetricsDefault as well as for other metrics.

For more information about appearance and behavior configuration, see Navigation Bars.

  • The navigation bar’s delegate object.

    Declaration

    Swift

    weak var delegate: UINavigationBarDelegate?

    Objective-C

    @property(nonatomic, weak) id< UINavigationBarDelegate > _Nullable delegate

    Discussion

    The delegate should conform to the UINavigationBarDelegate protocol. The default value is nil.

    If the navigation bar was created by a navigation controller and is being managed by that object, you must not change the value of this property. Navigation controllers act as the delegate for any navigation bars they create.

    Availability

    Available in iOS 2.0 and later.

  • Pushes the given navigation item onto the receiver’s stack and updates the navigation bar.

    Declaration

    Swift

    func pushNavigationItem(_ item: UINavigationItem, animated animated: Bool)

    Objective-C

    - (void)pushNavigationItem:(UINavigationItem * _Nonnull)item animated:(BOOL)animated

    Parameters

    item

    The navigation item to push on the stack.

    animated

    YEStrue if the navigation bar should be animated; otherwise, NOfalse.

    Discussion

    Pushing a navigation item displays the item’s title in the center on the navigation bar. The previous top navigation item (if it exists) is displayed as a back button on the left side of the navigation bar. If the new top item has a left custom view, it is displayed instead of the back button.

    Availability

    Available in iOS 2.0 and later.

  • Pops the top item from the receiver’s stack and updates the navigation bar.

    Declaration

    Swift

    func popNavigationItemAnimated(_ animated: Bool) -> UINavigationItem?

    Objective-C

    - (UINavigationItem * _Nullable)popNavigationItemAnimated:(BOOL)animated

    Parameters

    animated

    YEStrue if the navigation bar should be animated; otherwise, NOfalse.

    Return Value

    The top item that was popped.

    Discussion

    Popping a navigation item removes the top item from the stack and replaces it with the back item. The back item’s title is centered on the navigation bar and its other properties are displayed.

    Availability

    Available in iOS 2.0 and later.

  • Replaces the navigation items currently managed by the navigation bar with the specified items.

    Declaration

    Swift

    func setItems(_ items: [UINavigationItem]?, animated animated: Bool)

    Objective-C

    - (void)setItems:(NSArray<UINavigationItem *> * _Nullable)items animated:(BOOL)animated

    Parameters

    items

    The UINavigationItem objects to place in the stack. The front-to-back order of the items in this array represents the new bottom-to-top order of the items in the navigation stack. Thus, the last item added to the array becomes the top item of the navigation stack.

    animated

    If YEStrue, animate the pushing or popping of the top stack item. If NOfalse, replace the stack items without any animations.

    Discussion

    You can use this method to update or replace the navigation items in the stack without pushing or popping each item explicitly. In addition, this method lets you update the stack without animating the changes, which might be appropriate at launch time when you want to restore the state of the navigation stack to some previous state.

    If animations are enabled, this method decides which type of transition to perform based on whether the last item in the items array is already on the current navigation stack. If the item is currently on the stack, but is not the topmost item, this method uses a pop transition; if it is the topmost item, no transition is performed. If the item is not on the stack, this method uses a push transition. Only one transition is performed, but when that transition finishes, the entire contents of the stack are replaced with the new items. For example, if items A, B, and C are on the stack and you set items D, A, and B, this method uses a pop transition and the resulting stack contains the items D, A, and B.

    Availability

    Available in iOS 3.0 and later.

  • An array of navigation items managed by the navigation bar.

    Declaration

    Swift

    var items: [UINavigationItem]?

    Objective-C

    @property(nonatomic, copy) NSArray <UINavigationItem *> * _Nullable items

    Discussion

    The bottom item is at index 0, the back item is at index n-2, and the top item is at index n-1, where n is the number of items in the array.

    Availability

    Available in iOS 2.0 and later.

    See Also

    backItem
    topItem

  • The navigation item at the top of the navigation bar’s stack. (read-only)

    Declaration

    Swift

    var topItem: UINavigationItem? { get }

    Objective-C

    @property(nonatomic, readonly, strong) UINavigationItem * _Nullable topItem

    Availability

    Available in iOS 2.0 and later.

    See Also

    backItem
    items

  • The navigation item that is immediately below the topmost item on navigation bar’s stack. (read-only)

    Declaration

    Swift

    var backItem: UINavigationItem? { get }

    Objective-C

    @property(nonatomic, readonly, strong) UINavigationItem * _Nullable backItem

    Discussion

    If the leftBarButtonItem property of the topmost navigation item is nil, the navigation bar displays a back button whose title is derived from the item in this property.

    If there is only one item on the navigation bar’s stack, the value of this property is nil.

    Availability

    Available in iOS 2.0 and later.

    See Also

    topItem
    items