UINavigationController Class Reference

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

Overview

The UINavigationController class implements a specialized view controller that manages the navigation of hierarchical content. This navigation interface makes it possible to present your data efficiently and makes it easier for the user to navigate that content. You generally use this class as-is but in iOS 6 and later you may subclass to customize the class behavior.

The screens presented by a navigation interface typically mimic the hierarchical organization of your data. At each level of the hierarchy, you provide an appropriate screen (managed by a custom view controller) to display the content at that level. Figure 1 shows an example of the navigation interface presented by the Settings application in iOS Simulator. The first screen presents the user with the list of applications that contain preferences. Selecting an application reveals individual settings and groups of settings for that application. Selecting a group yields more settings and so on. For all but the root view, the navigation controller provides a back button to allow the user to move back up the hierarchy.

Figure 1  A sample navigation interface
A sample navigation interface

A navigation controller object manages the currently displayed screens using the navigation stack, which is represented by an array of view controllers. The first view controller in the array corresponds to the root view controller. The last view controller in the array represents the view controller currently being displayed. You modify the stack using the methods of the navigation controller object. Typically, you add a view controller to the top of the stack using the pushViewController:animated: method. Pushing a view controller displays its view in the navigation interface and updates the navigation controls accordingly. You typically push a view controller in response to user actions in the current view controller—for example, in response to the user tapping a row in a table.

To remove a view controller from the stack programmatically, you call the popViewControllerAnimated: method. The back button in the navigation bar also removes the topmost view controller and is the more common way to pop view controllers off the stack. In iOS 7 and later, the user can also pop the topmost view controller by initiating a swipe from the leftmost edge of the screen.

A navigation controller object tells its delegate about changes to the active view controller. You can assign a delegate to your navigation controller if you want to perform additional setup or cleanup tasks related to the pushing and popping of view controllers. The delegate object you provide must conform to the UINavigationControllerDelegate protocol.

For more information about how to integrate navigation controllers into your application, see View Controller Catalog for iOS. For additional information about view controllers, see View Controller Programming Guide for iOS.

Navigation Controller Views

A navigation controller is a container view controller—that is, it embeds the content of other view controllers inside of itself. You access a navigation controller’s view from its view property. This view incorporates the navigation bar, an optional toolbar, and the content view corresponding to the topmost view controller. Figure 2 shows how these views are assembled to present the overall navigation interface. (In this figure, the navigation interface is further embedded inside a tab bar interface.) Although the content of the navigation bar and toolbar views changes, the views themselves do not. The only view that actually changes is the custom content view provided by the topmost view controller on the navigation stack.

Figure 2  The views of a navigation controller
The views of a navigation controller

The navigation controller manages the creation, configuration, and display of the navigation bar and optional navigation toolbar. It is permissible to customize the navigation bar’s appearance-related properties but you must never change its frame, bounds, or alpha values directly. If you subclass UINavigationBar, you must initialize your navigation controller using the initWithNavigationBarClass:toolbarClass: method. To hide or show the navigation bar, use the navigationBarHidden property or setNavigationBarHidden:animated: method.

A navigation controller builds the contents of the navigation bar dynamically using the navigation item objects (instances of the UINavigationItem class) associated with the view controllers on the navigation stack. To change the contents of the navigation bar, you must therefore configure the navigation items of your custom view controllers. For more information about navigation items, see UINavigationItem Class Reference.

Updating the Navigation Bar

When the user changes the top-level view controller, the navigation controller updates the navigation bar accordingly. Specifically, the navigation controller updates the bar button items displayed in each of the three navigation bar positions: left, middle, and right. Bar button items are instances of the UIBarButtonItem class. You can create items with custom content or create standard system items depending on your needs. For more information about how to create bar button items, see UIBarButtonItem Class Reference.

For all but the root view controller on the navigation stack, the item on the left side of the navigation bar provides navigation back to the previous view controller. The contents of this left-most button are determined as follows:

  • If the new top-level view controller has a custom left bar button item, that item is displayed. To specify a custom left bar button item, set the leftBarButtonItem property of the view controller’s navigation item.

  • If the top-level view controller does not have a custom left bar button item, but the navigation item of the previous view controller has an object in its backBarButtonItem property, the navigation bar displays that item.

  • If a custom bar button item is not specified by either of the view controllers, a default back button is used and its title is set to the value of the title property of the previous view controller—that is, the view controller one level down on the stack. (If there is only one view controller on the navigation stack, no back button is displayed.)

The navigation controller updates the middle of the navigation bar as follows:

  • If the new top-level view controller has a custom title view, the navigation bar displays that view in place of the default title view. To specify a custom title view, set the titleView property of the view controller’s navigation item.

  • If no custom title view is set, the navigation bar displays a label containing the view controller’s default title. The string for this label is usually obtained from the title property of the view controller itself. If you want to display a different title than the one associated with the view controller, set the title property of the view controller’s navigation item instead.

The navigation controller updates the right side of the navigation bar as follows:

  • If the new top-level view controller has a custom right bar button item, that item is displayed. To specify a custom right bar button item, set the rightBarButtonItem property of the view controller’s navigation item.

  • If no custom right bar button item is specified, the navigation bar displays nothing on the right side of the bar.

The navigation controller updates the navigation bar each time the top view controller changes. Thus, these changes occur each time a view controller is pushed onto the stack or popped from it. When you animate a push or pop operation, the navigation controller similarly animates the change to the navigation bar content.

Tinting of the navigation bar is controlled by properties of the navigation bar itself. Use the tintColor property to change the tint color of items in the bar and use the barTintColor property to change the tint color of the bar itself. Navigation bars do not inherit their tint color from the currently displayed view controller.

For more information about the navigation bar, see UINavigationBar Class Reference.

Displaying a Navigation Toolbar

A navigation controller object manages an optional toolbar in its view hierarchy. When displayed, this toolbar obtains its current set of items from the toolbarItems property of the active view controller. When the active view controller changes, the navigation controller updates the toolbar items to match the new view controller, animating the new items into position when appropriate.

The navigation toolbar is hidden by default but you can show it for your navigation interface by calling the setToolbarHidden:animated: method of your navigation controller object. If not all of your view controllers support toolbar items, your delegate object can call this method to toggle the visibility of the toolbar during subsequent push and pop operations. To use a custom UIToolbar subclass, use the initWithNavigationBarClass:toolbarClass: method to initialize the navigation controller.

State Preservation

In iOS 6 and later, if you assign a value to this view controller’s restorationIdentifier property, it attempts to preserve the child view controllers on its navigation stack. The navigation controller starts at the bottom of the stack and moves upward, encoding each view controller that also has a valid restoration identifier string. During the next launch cycle, the navigation controller restores the preserved view controllers to the navigation stack in the same order that they were preserved.

The child view controllers you push onto the navigation stack may use the same restoration identifiers. The navigation controller automatically stores additional information to ensure that each child’s restoration path is unique.

For more information about how state preservation and restoration works, see iOS App Programming Guide.

Tasks

Creating Navigation Controllers

Accessing Items on the Navigation Stack

Pushing and Popping Stack Items

Configuring Navigation Bars

Accessing the Delegate

Configuring Custom Toolbars

Properties

delegate

The delegate of the navigation controller object.

@property(nonatomic, assign) id<UINavigationControllerDelegate> delegate
Discussion

You can use the navigation delegate to perform additional actions in response to changes in the navigation interface. For more information about implementing the delegate, see UINavigationControllerDelegate Protocol Reference.

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

interactivePopGestureRecognizer

The gesture recognizer responsible for popping the top view controller off the navigation stack. (read-only)

@property(nonatomic, readonly) UIGestureRecognizer *interactivePopGestureRecognizer
Discussion

The navigation controller installs this gesture recognizer on its view and uses it to pop the topmost view controller off the navigation stack. You can use this property to retrieve the gesture recognizer and tie it to the behavior of other gesture recognizers in your user interface. When tying your gesture recognizers together, make sure they recognize their gestures simultaneously to ensure that your gesture recognizers are given a chance to handle the event.

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

navigationBar

The navigation bar managed by the navigation controller. (read-only)

@property(nonatomic, readonly) UINavigationBar *navigationBar
Discussion

It is permissible to customize the appearance of the navigation bar using the methods and properties of the UINavigationBar class but you must never change its frame, bounds, or alpha values or modify its view hierarchy directly. To show or hide the navigation bar, you should always do so through the navigation controller by changing its navigationBarHidden property or calling the setNavigationBarHidden:animated: method.

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

navigationBarHidden

A Boolean value that indicates whether the navigation bar is hidden.

@property(nonatomic, getter=isNavigationBarHidden) BOOL navigationBarHidden
Discussion

If YES, the navigation bar is hidden. The default value is NO. Setting this property changes the visibility of the navigation bar without animating the changes. If you want to animate the change, use the setNavigationBarHidden:animated:method instead.

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

toolbar

The custom toolbar associated with the navigation controller. (read-only)

@property(nonatomic,readonly) UIToolbar *toolbar
Discussion

This property contains a reference to the built-in toolbar managed by the navigation controller. Access to this toolbar is provided solely for clients that want to present an action sheet from the toolbar. You should not modify the UIToolbar object directly.

Management of this toolbar’s contents is done through the custom view controllers associated with this navigation controller. For each view controller on the navigation stack, you can assign a custom set of toolbar items using the setToolbarItems:animated: method of UIViewController.

The visibility of this toolbar is controlled by the toolbarHidden property. The toolbar also obeys the hidesBottomBarWhenPushed property of the currently visible view controller and hides and shows itself automatically as needed.

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

toolbarHidden

A Boolean indicating whether the navigation controller’s built-in toolbar is visible.

@property(nonatomic,getter=isToolbarHidden) BOOL toolbarHidden
Discussion

If this property is set to YES, the toolbar is not visible. The default value of this property is YES.

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

topViewController

The view controller at the top of the navigation stack. (read-only)

@property(nonatomic, readonly, retain) UIViewController *topViewController
Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationController.h

viewControllers

The view controllers currently on the navigation stack.

@property(nonatomic, copy) NSArray *viewControllers
Discussion

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

Assigning a new array of view controllers to this property is equivalent to calling the setViewControllers:animated: method with the animated parameter set to NO.

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

visibleViewController

The view controller associated with the currently visible view in the navigation interface. (read-only)

@property(nonatomic, readonly, retain) UIViewController *visibleViewController
Discussion

The currently visible view can belong either to the view controller at the top of the navigation stack or to a view controller that was presented modally on top of the navigation controller itself.

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

Instance Methods

initWithNavigationBarClass:toolbarClass:

Initializes and returns a newly created navigation controller that uses your custom bar subclasses.

- (instancetype)initWithNavigationBarClass:(Class)navigationBarClass toolbarClass:(Class)toolbarClass
Parameters
navigationBarClass

Specify the custom UINavigationBar subclass you want to use, or specify nil to use the standard UINavigationBar class.

toolbarClass

Specify the custom UIToolbar subclass you want to use, or specify nil to use the standard UIToolbar class.

Return Value

The initialized navigation controller object or nil if there was a problem initializing the object.

Discussion

Use this initialization method if you want to use custom navigation bar or toolbar subclasses with the navigation controller. If you use this method, you are responsible for adding a root view controller before presenting the navigation controller onscreen.

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

initWithRootViewController:

Initializes and returns a newly created navigation controller.

- (id)initWithRootViewController:(UIViewController *)rootViewController
Parameters
rootViewController

The view controller that resides at the bottom of the navigation stack. This object cannot be an instance of the UITabBarController class.

Return Value

The initialized navigation controller object or nil if there was a problem initializing the object.

Discussion

This is a convenience method for initializing the receiver and pushing a root view controller onto the navigation stack. Every navigation stack must have at least one view controller to act as the root.

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

popToRootViewControllerAnimated:

Pops all the view controllers on the stack except the root view controller and updates the display.

- (NSArray *)popToRootViewControllerAnimated:(BOOL)animated
Parameters
animated

Set this value to YES to animate the transition. Pass NO if you are setting up a navigation controller before its view is displayed.

Return Value

An array of view controllers representing the items that were popped from the stack.

Discussion

The root view controller becomes the top view controller. For information on how the navigation bar is updated, see “Updating the Navigation Bar.”

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

popToViewController:animated:

Pops view controllers until the specified view controller is at the top of the navigation stack.

- (NSArray *)popToViewController:(UIViewController *)viewController animated:(BOOL)animated
Parameters
viewController

The view controller that you want to be at the top of the stack. This view controller must currently be on the navigation stack.

animated

Set this value to YES to animate the transition. Pass NO if you are setting up a navigation controller before its view is displayed.

Return Value

An array containing the view controllers that were popped from the stack.

Discussion

For information on how the navigation bar is updated, see “Updating the Navigation Bar.”

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

popViewControllerAnimated:

Pops the top view controller from the navigation stack and updates the display.

- (UIViewController *)popViewControllerAnimated:(BOOL)animated
Parameters
animated

Set this value to YES to animate the transition. Pass NO if you are setting up a navigation controller before its view is displayed.

Return Value

The view controller that was popped from the stack.

Discussion

This method removes the top view controller from the stack and makes the new top of the stack the active view controller. If the view controller at the top of the stack is the root view controller, this method does nothing. In other words, you cannot pop the last item on the stack.

In addition to displaying the view associated with the new view controller at the top of the stack, this method also updates the navigation bar and tool bar accordingly. For information on how the navigation bar is updated, see “Updating the Navigation Bar.”

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

pushViewController:animated:

Pushes a view controller onto the receiver’s stack and updates the display.

- (void)pushViewController:(UIViewController *)viewController animated:(BOOL)animated
Parameters
viewController

The view controller to push onto the stack. This object cannot be a tab bar controller. If the view controller is already on the navigation stack, this method throws an exception.

animated

Specify YES to animate the transition or NO if you do not want the transition to be animated. You might specify NO if you are setting up the navigation controller at launch time.

Discussion

The object in the viewController parameter becomes the top view controller on the navigation stack. Pushing a view controller causes its view to be embedded in the navigation interface. If the animated parameter is YES, the view is animated into position; otherwise, the view is simply displayed in its final location.

In addition to displaying the view associated with the new view controller at the top of the stack, this method also updates the navigation bar and tool bar accordingly. For information on how the navigation bar is updated, see “Updating the Navigation Bar.”

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

setNavigationBarHidden:animated:

Sets whether the navigation bar is hidden.

- (void)setNavigationBarHidden:(BOOL)hidden animated:(BOOL)animated
Parameters
hidden

Specify YES to hide the navigation bar or NO to show it.

animated

Specify YES if you want to animate the change in visibility or NO if you want the navigation bar to appear immediately.

Discussion

For animated transitions, the duration of the animation is specified by the value in the UINavigationControllerHideShowBarDuration constant.

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

setToolbarHidden:animated:

Changes the visibility of the navigation controller’s built-in toolbar.

- (void)setToolbarHidden:(BOOL)hidden animated:(BOOL)animated
Parameters
hidden

Specify YES to hide the toolbar or NO to show it.

animated

Specify YES if you want the toolbar to be animated on or off the screen.

Discussion

You can use this method to animate changes to the visibility of the built-in toolbar.

Calling this method with the animated parameter set to NO is equivalent to setting the value of the toolbarHidden property directly. The toolbar simply appears or disappears depending on the value in the hidden parameter.

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

setViewControllers:animated:

Replaces the view controllers currently managed by the navigation controller with the specified items.

- (void)setViewControllers:(NSArray *)viewControllers animated:(BOOL)animated
Parameters
viewControllers

The view controllers to place in the stack. The front-to-back order of the controllers in this array represents the new bottom-to-top order of the controllers 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 view controller. If NO, replace the view controllers without any animations.

Discussion

Use this method to update or replace the current view controller stack without pushing or popping each controller explicitly. In addition, this method lets you update the set of controllers without animating the changes, which might be appropriate at launch time when you want to return the navigation controller to a 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 in the navigation stack. If the view controller is currently in 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 view controller 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 view controllers. For example, if controllers A, B, and C are on the stack and you set controllers D, A, and B, this method uses a pop transition and the resulting stack contains the controllers D, A, and B.

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

Constants

UINavigationControllerHideShowBarDuration

A global constant that specifies a preferred duration when animating the navigation bar.

extern const CGFloat UINavigationControllerHideShowBarDuration
Constants
UINavigationControllerHideShowBarDuration

This variable specifies the duration when animating the navigation bar. Note that this is a constant value, so it cannot be set.

Available in iOS 2.0 and later.

Declared in UINavigationController.h.