UINavigationBar Class Reference

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

Overview

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

Tasks

Assigning the Delegate

Pushing and Popping Items

Customizing the Bar Appearance

Properties

backIndicatorImage

The image shown beside the back button.

@property(nonatomic, retain) UIImage *backIndicatorImage
Discussion

If you want to customize the back indicator image, you must also set backIndicatorTransitionMaskImage.

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

backIndicatorTransitionMaskImage

The image used as a mask for content during push and pop transitions.

@property(nonatomic, retain) UIImage *backIndicatorTransitionMaskImage
Discussion

If you want to customize the back indicator image, you must also set backIndicatorImage.

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

backItem

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

@property(nonatomic, readonly, retain) UINavigationItem *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.
Declared In
UINavigationBar.h

barStyle

The navigation bar style that specifies its appearance.

@property(nonatomic, assign) UIBarStyle barStyle
Discussion

See UIBarStyle for possible values. The default value is UIBarStyleDefault.

It is permissible to set the value of this property when the navigation bar is being managed by a navigation controller object.

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

barTintColor

The tint color to apply to the navigation bar background.

@property(nonatomic, retain) UIColor *barTintColor
Discussion

This color is made translucent by default unless you set the translucent property to NO.

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

delegate

The navigation bar’s delegate object.

@property(nonatomic, assign) id 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.
Declared In
UINavigationBar.h

items

An array of navigation items managed by the navigation bar.

@property(nonatomic, copy) NSArray *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.
Declared In
UINavigationBar.h

shadowImage

The shadow image to be used for the navigation bar.

@property(nonatomic, retain) UIImage *shadowImage
Discussion

The default value is nil, which corresponds to the default shadow image. When non-nil, this property represents a custom shadow image to show instead of the default. For a custom shadow image to be shown, a custom background image must also be set with the setBackgroundImage:forBarMetrics: method. If the default background image is used, then the default shadow image will be used regardless of the value of this property.

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

tintColor

The tint color to apply to the navigation items and bar button items.

@property(nonatomic, retain) UIColor *tintColor
Discussion

In iOS v7.0, all subclasses of UIView derive their behavior for tintColor from the base class. See the discussion of tintColor at the UIView level for more information.

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

titleTextAttributes

Display attributes for the bar’s title text.

@property(nonatomic, copy) NSDictionary *titleTextAttributes
Discussion

You can specify the font, text color, text shadow color, and text shadow offset for the title in the text attributes dictionary, using the text attribute keys described in NSString UIKit Additions Reference.

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

topItem

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

@property(nonatomic, readonly, retain) UINavigationItem *topItem
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UINavigationBar.h

translucent

A Boolean value indicating whether the navigation bar is translucent (YES) or not (NO).

@property(nonatomic, assign, getter=isTranslucent) BOOL translucent
Discussion

The default value is YES. If the navigation bar has a custom background image, the default is YES if any pixel of the image has an alpha value of less than 1.0, and NO otherwise.

If you set this property to YES on a navigation bar with an opaque custom background image, the navigation bar will apply a system opacity less than 1.0 to the image.

If you set this property to NO on a navigation bar with a translucent custom background image, the navigation bar provides an opaque background for the image using black if the navigation bar has UIBarStyleBlack style, white if the navigation bar has UIBarStyleDefault, or the navigation bar’s barTintColor if a custom value is defined.

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

Instance Methods

backgroundImageForBarMetrics:

Returns the background image for given bar metrics.

- (UIImage *)backgroundImageForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

A bar metrics constant.

Return Value

The background image for barMetrics.

Discussion

Same as backgroundImageForBarPosition:barMetrics: with a position of UIBarPositionAny.

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

backgroundImageForBarPosition:barMetrics:

Returns the background image to use for a given bar position and set of metrics.

- (UIImage *)backgroundImageForBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics
Parameters
barPosition

The location of the navigation bar.

barMetrics

The metrics of the navigation bar.

Return Value

The image to use for the specified location and metrics.

Discussion

Resizable images will be stretched vertically if necessary for a position of UIBarPositionTopAttached.

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

popNavigationItemAnimated:

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

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

YES if the navigation bar should be animated; otherwise, NO.

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.
Declared In
UINavigationBar.h

pushNavigationItem:animated:

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

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

The navigation item to push on the stack.

animated

YES if the navigation bar should be animated; otherwise, NO.

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.
Declared In
UINavigationBar.h

setBackgroundImage:forBarMetrics:

Sets the background image for given bar metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forBarMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The background image to use for barMetrics.

barMetrics

A bar metrics constant.

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

setBackgroundImage:forBarPosition:barMetrics:

Sets the background image to use for a given bar position and set of metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The image to use for the specified location and metrics.

barPosition

The location of the navigation bar.

barMetrics

The metrics of the navigation bar.

Discussion

Resizable images will be stretched vertically if necessary for a position of UIBarPositionTopAttached.

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

setItems:animated:

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

- (void)setItems:(NSArray *)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 YES, animate the pushing or popping of the top stack item. If NO, 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.
Declared In
UINavigationBar.h

setTitleVerticalPositionAdjustment:forBarMetrics:

Sets the title’s vertical position adjustment for given bar metrics.

- (void)setTitleVerticalPositionAdjustment:(CGFloat)adjustment forBarMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The title’s vertical position adjustment for barMetrics.

barMetrics

A bar metrics constant.

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

titleVerticalPositionAdjustmentForBarMetrics:

Returns the title’s vertical position adjustment for given bar metrics.

- (CGFloat)titleVerticalPositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

A bar metrics constant.

Return Value

The title’s vertical position adjustment for barMetrics.

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