iOS Developer Library

Developer

UIKit Framework Reference UINavigationItem Class Reference

Options
Deployment Target:

On This Page
Language:

UINavigationItem

A UINavigationItem object manages the buttons and views to be displayed in a UINavigationBar object. When building a navigation interface, each view controller pushed onto the navigation stack must have a UINavigationItem object that contains the buttons and views it wants displayed in the navigation bar. The managing UINavigationController object uses the navigation items of the topmost two view controllers to populate the navigation bar with content.

A navigation item always reflects information about the view controller with which it is associated. The navigation item must provide a title to display when the view controller is topmost on the navigation stack. In addition, the item may contain additional buttons to display on the right side of the navigation bar. You can specify buttons and views to display on the left side of the toolbar using the leftBarButtonItems property but the navigation controller displays those buttons only if there is space available.

The backBarButtonItem property of a navigation item reflects the back button you want displayed when the current view controller is just below the topmost view controller. In other words, the back button is not used when the current view controller is topmost.

When specifying buttons for a navigation item, you must use UIBarButtonItem objects. If you want to display custom views in the navigation bar, you must wrap those views inside a UIBarButtonItem object before adding them to the navigation item.

For information about how navigation items work together with a navigation controller, custom view controllers, and the navigation bar to display their content, see View Controller Programming Guide for iOS.

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • Returns a navigation item initialized with the specified title.

    Declaration

    Swift

    init(title title: String?)

    Objective-C

    - (instancetype)initWithTitle:(NSString *)title

    Parameters

    title

    The string to set as the navigation item’s title displayed in the center of the navigation bar.

    Return Value

    A new UINavigationItem object initialized with the specified title.

    Discussion

    This is the designated initializer for this class.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    title

  • title title Property

    The navigation item’s title displayed in the center of the navigation bar.

    Declaration

    Swift

    var title: String?

    Objective-C

    @property(nonatomic, copy) NSString *title

    Discussion

    The default value is nil.

    When the receiver is on the navigation item stack and is second from the top—in other words, its view controller manages the views that the user would navigate back to—the value in this property is used for the back button on the top-most navigation bar. If the value of this property is nil, the system uses the string “Back” as the text of the back button.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • prompt prompt Property

    A single line of text displayed at the top of the navigation bar.

    Declaration

    Swift

    var prompt: String?

    Objective-C

    @property(nonatomic, copy) NSString *prompt

    Discussion

    The default value is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The bar button item to use when a back button is needed on the navigation bar.

    Declaration

    Swift

    var backBarButtonItem: UIBarButtonItem?

    Objective-C

    @property(nonatomic, retain) UIBarButtonItem *backBarButtonItem

    Discussion

    When this navigation item is immediately below the top item in the stack, the navigation controller derives the back button for the navigation bar from this navigation item. When this property is nil, the navigation item uses the value in its title property to create an appropriate back button. If you want to specify a custom image or title for the back button, you can assign a custom bar button item (with your custom title or image) to this property instead. When configuring your bar button item, do not assign a custom view to it; the navigation item ignores custom views in the back bar button anyway.

    The default value of this property is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that determines whether the back button is hidden.

    Declaration

    Swift

    var hidesBackButton: Bool

    Objective-C

    @property(nonatomic, assign) BOOL hidesBackButton

    Discussion

    When set to YEStrue, the back button is hidden when this navigation item is the top item. This is true regardless of the value in the leftItemsSupplementBackButton property. When set to NOfalse, the back button is shown if it is still present. (It can be replaced by values in either the leftBarButtonItem or leftBarButtonItems properties.) The default value is NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sets whether the back button is hidden, optionally animating the transition.

    Declaration

    Swift

    func setHidesBackButton(_ hidesBackButton: Bool, animated animated: Bool)

    Objective-C

    - (void)setHidesBackButton:(BOOL)hidesBackButton animated:(BOOL)animated

    Parameters

    hidesBackButton

    Specify YEStrue if the back button should be hidden when this navigation item is the top item. Specify NOfalse if the back button should be visible, assuming it has not been replaced by a custom item.

    animated

    YEStrue to animate the transition; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the left items are displayed in addition to the back button.

    Declaration

    Swift

    var leftItemsSupplementBackButton: Bool

    Objective-C

    @property(nonatomic) BOOL leftItemsSupplementBackButton

    Discussion

    Normally, the presence of custom left bar button items causes the back button to be removed in favor of the custom items. Setting this property to YEStrue causes the items in the leftBarButtonItems or leftBarButtonItem property to be displayed to the right of the back button—that is, they are displayed in addition to, and not instead of, the back button. When set to NOfalse, the items in those properties are displayed instead of the back button. The default value of this property is NOfalse.

    The value in the hidesBackButton property still determines whether the back button is actually displayed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • titleView titleView Property

    A custom view displayed in the center of the navigation bar when the receiver is the top item.

    Declaration

    Swift

    var titleView: UIView?

    Objective-C

    @property(nonatomic, retain) UIView *titleView

    Discussion

    If this property value is nil, the navigation item’s title is displayed in the center of the navigation bar when the receiver is the top item. If you set this property to a custom title, it is displayed instead of the title. This property is ignored if leftBarButtonItem is not nil.

    Custom views can contain buttons. Use the buttonWithType: method in UIButton class to add buttons to your custom view in the style of the navigation bar. Custom title views are centered on the navigation bar and may be resized to fit.

    The default value is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • An array of custom bar button items to display on the left side of the navigation bar when the receiver is the top navigation item.

    Declaration

    Swift

    var leftBarButtonItems: [AnyObject]?

    Objective-C

    @property(nonatomic, copy) NSArray *leftBarButtonItems

    Discussion

    This array can contain 0 or more bar items to display on the left side of the navigation bar. Items can include fixed-width and flexible-width spaces. If the leftItemsSupplementBackButton property is YEStrue, the items are displayed to the right of the back button, otherwise the items replace the back button and start at the left edge of the bar. Items are displayed left-to-right in the same order as they appear in the array.

    If there is not enough room to display all of the items in the array, those that would overlap the title view (if present) or the buttons on the right side of the bar are not displayed.

    The first item in the array can also be set using the leftBarButtonItem property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • A custom bar button item displayed on the left of the navigation bar when the receiver is the top navigation item.

    Declaration

    Swift

    var leftBarButtonItem: UIBarButtonItem?

    Objective-C

    @property(nonatomic, retain) UIBarButtonItem *leftBarButtonItem

    Discussion

    In iOS 5.0 and later, the contents of this property always refer to the first bar button item in the leftBarButtonItems array. Assigning a new value to this property replaces the first item in the leftBarButtonItems array with the new value. Setting this property to nil removes the first item in the array. If the bar button item is already in the array, it is moved from its current location to the front of the array.

    Prior to iOS 5.0, this property contained the single bar item to display on the left side of the navigation bar instead of the back button.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • An array of custom bar button items to display on the right side of the navigation bar when the receiver is the top navigation item.

    Declaration

    Swift

    var rightBarButtonItems: [AnyObject]?

    Objective-C

    @property(nonatomic, copy) NSArray *rightBarButtonItems

    Discussion

    This array can contain 0 or more bar button items to display on the right side of the navigation bar. Items are displayed right-to-left in the same order as they appear in the array. Thus, the first item in the array is the rightmost item and other items are added to the left of the previous item.

    If there is not enough room to display all of the items in the array, those that would overlap the title view (if present) or the buttons on the left side of the bar are not displayed.

    The first item in the array can also be set using the rightBarButtonItem property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • A custom bar button item displayed on the right of the navigation bar when the receiver is the top navigation item.

    Declaration

    Swift

    var rightBarButtonItem: UIBarButtonItem?

    Objective-C

    @property(nonatomic, retain) UIBarButtonItem *rightBarButtonItem

    Discussion

    In iOS 5.0 and later, the contents of this property always refer to the first bar button item in the rightBarButtonItems array. Assigning a new value to this property replaces the first item in the rightBarButtonItems array with the new value. Setting this property to nil removes the first item in the array. If the bar button item is already in the array, it is moved from its current location to the front of the array.

    Prior to iOS 5.0, this property contained the single bar item to display on the right side of the navigation bar.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sets the left bar button items, optionally animating the transition to the new items.

    Declaration

    Swift

    func setLeftBarButtonItems(_ items: [AnyObject]?, animated animated: Bool)

    Objective-C

    - (void)setLeftBarButtonItems:(NSArray *)items animated:(BOOL)animated

    Parameters

    items

    An array of custom bar button items to display on the left side of the navigation bar.

    animated

    Specify YEStrue to animate the transition to the custom bar items when this item is the top item. Specify NOfalse to set the items immediately without animating the change.

    Discussion

    If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Sets the custom bar button item, optionally animating the transition to the new item.

    Declaration

    Swift

    func setLeftBarButtonItem(_ item: UIBarButtonItem?, animated animated: Bool)

    Objective-C

    - (void)setLeftBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated

    Parameters

    item

    A custom bar item to display on the left side of the navigation bar.

    animated

    Specify YEStrue to animate the transition to the custom bar item when this item is the top item. Specify NOfalse to set the item immediately without animating the change.

    Discussion

    If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sets the right bar button items, optionally animating the transition to the new items.

    Declaration

    Swift

    func setRightBarButtonItems(_ items: [AnyObject]?, animated animated: Bool)

    Objective-C

    - (void)setRightBarButtonItems:(NSArray *)items animated:(BOOL)animated

    Parameters

    items

    An array of custom bar button items to display on the right side of the navigation bar.

    animated

    Specify YEStrue to animate the transition to the custom bar items when this item is the top item. Specify NOfalse to set the items immediately without animating the change.

    Discussion

    If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Sets the custom bar button item, optionally animating the transition to the view.

    Declaration

    Swift

    func setRightBarButtonItem(_ item: UIBarButtonItem?, animated animated: Bool)

    Objective-C

    - (void)setRightBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated

    Parameters

    item

    A custom bar item to display on the right of the navigation bar.

    animated

    Specify YEStrue to animate the transition to the custom bar item when this item is the top item. Specify NOfalse to set the item immediately without animating the change.

    Discussion

    If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.