UINavigationItem Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UINavigationBar.h
Related sample code

Overview

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.

Tasks

Initializing an Item

Getting and Setting Properties

Customizing Views

Properties

backBarButtonItem

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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

hidesBackButton

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

@property(nonatomic, assign) BOOL hidesBackButton
Discussion

When set to YES, 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 NO, 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 NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

leftBarButtonItem

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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

leftBarButtonItems

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.

@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 YES, 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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

leftItemsSupplementBackButton

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

@property 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 YES 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 NO, the items in those properties are displayed instead of the back button. The default value of this property is NO.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

prompt

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

@property(nonatomic, copy) NSString *prompt
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UINavigationBar.h

rightBarButtonItem

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

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UINavigationBar.h

rightBarButtonItems

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.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

title

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

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UINavigationBar.h

titleView

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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

Instance Methods

initWithTitle:

Returns a navigation item initialized with the specified title.

- (id)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.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

setHidesBackButton:animated:

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

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

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

animated

YES to animate the transition; otherwise, NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

setLeftBarButtonItem:animated:

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

- (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 YES to animate the transition to the custom bar item when this item is the top item. Specify NO 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

setLeftBarButtonItems:animated:

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

- (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 YES to animate the transition to the custom bar items when this item is the top item. Specify NO 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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

setRightBarButtonItem:animated:

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

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

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

animated

Specify YES to animate the transition to the custom bar item when this item is the top item. Specify NO 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

setRightBarButtonItems:animated:

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

- (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 YES to animate the transition to the custom bar items when this item is the top item. Specify NO 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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h