iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UINavigationController Class Reference

Options
Deployment Target:

On This Page
Language:

UINavigationController

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

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • Initializes and returns a newly created navigation controller.

    Declaration

    Swift

    init(rootViewController rootViewController: UIViewController)

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(navigationBarClass navigationBarClass: AnyClass?, toolbarClass toolbarClass: AnyClass?)

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var topViewController: UIViewController! { get }

    Objective-C

    @property(nonatomic, readonly, retain) UIViewController *topViewController

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var visibleViewController: UIViewController! { get }

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The view controllers currently on the navigation stack.

    Declaration

    Swift

    var viewControllers: [AnyObject]!

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func setViewControllers(_ viewControllers: [AnyObject]!, animated animated: Bool)

    Objective-C

    - (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 YEStrue, animate the pushing or popping of the top view controller. If NOfalse, 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func pushViewController(_ viewController: UIViewController, animated animated: Bool)

    Objective-C

    - (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 YEStrue to animate the transition or NOfalse if you do not want the transition to be animated. You might specify NOfalse 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 YEStrue, 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func popViewControllerAnimated(_ animated: Bool) -> UIViewController?

    Objective-C

    - (UIViewController *)popViewControllerAnimated:(BOOL)animated

    Parameters

    animated

    Set this value to YEStrue to animate the transition. Pass NOfalse 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func popToRootViewControllerAnimated(_ animated: Bool) -> [AnyObject]?

    Objective-C

    - (NSArray *)popToRootViewControllerAnimated:(BOOL)animated

    Parameters

    animated

    Set this value to YEStrue to animate the transition. Pass NOfalse 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func popToViewController(_ viewController: UIViewController, animated animated: Bool) -> [AnyObject]?

    Objective-C

    - (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 YEStrue to animate the transition. Pass NOfalse 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var interactivePopGestureRecognizer: UIGestureRecognizer! { get }

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var navigationBar: UINavigationBar { get }

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sets whether the navigation bar is hidden.

    Declaration

    Swift

    func setNavigationBarHidden(_ hidden: Bool, animated animated: Bool)

    Objective-C

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

    Parameters

    hidden

    Specify YEStrue to hide the navigation bar or NOfalse to show it.

    animated

    Specify YEStrue if you want to animate the change in visibility or NOfalse 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the navigation controller allows hiding of its bars using a tap gesture.

    Declaration

    Swift

    var hidesBarsOnTap: Bool

    Objective-C

    @property(nonatomic, readwrite, assign) BOOL hidesBarsOnTap

    Discussion

    When the value of this property is YEStrue, the navigation controller toggles the hiding and showing of its navigation bar and toolbar in response to an otherwise unhandled tap in the content area. The default value of this property is NOfalse.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the navigation bar hides its bars in response to a swipe gesture.

    Declaration

    Swift

    var hidesBarsOnSwipe: Bool

    Objective-C

    @property(nonatomic, readwrite, assign) BOOL hidesBarsOnSwipe

    Discussion

    When this property is set to YEStrue, an upward swipe hides the navigation bar and toolbar. A downward swipe shows both bars again. If the toolbar does not have any items, it remains visible even after a swipe. The default value of this property is NOfalse.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the navigation controller hides its bars in a vertically compact environment.

    Declaration

    Swift

    var hidesBarsWhenVerticallyCompact: Bool

    Objective-C

    @property(nonatomic, readwrite, assign) BOOL hidesBarsWhenVerticallyCompact

    Discussion

    When the value of this property is YEStrue, the navigation controller hides its navigation bar and toolbar when it transitions to a vertically compact environment. Upon returning to a vertically regular environment, the navigation controller automatically shows both bars again. In addition, unhandled taps in the content area cause the navigation controller to show both bars again. The default value of this property is NOfalse.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the navigation controller hides its bars when the keyboard appears.

    Declaration

    Swift

    var hidesBarsWhenKeyboardAppears: Bool

    Objective-C

    @property(nonatomic, readwrite, assign) BOOL hidesBarsWhenKeyboardAppears

    Discussion

    When this property is set to YEStrue, the appearance of the keyboard causes the navigation controller to hide its navigation bar and toolbar. The default value of this property is NOfalse.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var navigationBarHidden: Bool

    Objective-C

    @property(nonatomic, getter=isNavigationBarHidden) BOOL navigationBarHidden

    Discussion

    If YEStrue, the navigation bar is hidden. The default value is NOfalse. 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The gesture recognizer used to hide and show the navigation and toolbar. (read-only)

    Declaration

    Swift

    unowned(unsafe) var barHideOnTapGestureRecognizer: UITapGestureRecognizer { get }

    Objective-C

    @property(nonatomic, readonly, assign) UITapGestureRecognizer *barHideOnTapGestureRecognizer

    Discussion

    This property contains the gesture recognizer used to hide or show the bars. The gesture recognizer is inactive unless the hidesBarsOnTap property is YEStrue. You can make changes to the gesture recognizer as needed but must not change its delegate and you must not remove the default target object and action that come configured with it. Do not try to replace this gesture recognizer by overriding the property.

    If you tie this gesture recognizer to one of your own, make sure both recognize their gestures simultaneously to ensure that each has a chance to handle the event.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The gesture recognizer used to hide the navigation bar and toolbar. (read-only)

    Declaration

    Swift

    var barHideOnSwipeGestureRecognizer: UIPanGestureRecognizer { get }

    Objective-C

    @property(nonatomic, readonly, retain) UIPanGestureRecognizer *barHideOnSwipeGestureRecognizer

    Discussion

    This property contains the gesture recognizer used to hide and show the navigation bar and toolbar. The gesture recognizer is inactive unless the hidesBarsOnSwipe property is YEStrue. You can make changes to the gesture recognizer as needed but must not change its delegate and you must not remove the default target object and action that come configured with it. Do not try to replace this gesture recognizer by overriding the property.

    If you tie this gesture recognizer to one of your own, make sure both recognize their gestures simultaneously to ensure that each has a chance to handle the event.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • toolbar toolbar Property

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

    Declaration

    Swift

    var toolbar: UIToolbar! { get }

    Objective-C

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    See Also

    toolbarHidden

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

    Declaration

    Swift

    func setToolbarHidden(_ hidden: Bool, animated animated: Bool)

    Objective-C

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

    Parameters

    hidden

    Specify YEStrue to hide the toolbar or NOfalse to show it.

    animated

    Specify YEStrue 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 NOfalse 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    See Also

    toolbarHidden

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

    Declaration

    Swift

    var toolbarHidden: Bool

    Objective-C

    @property(nonatomic, getter=isToolbarHidden) BOOL toolbarHidden

    Discussion

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

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Presents the specified view controller in the navigation interface.

    Declaration

    Swift

    func showViewController(_ vc: UIViewController, sender sender: AnyObject!)

    Objective-C

    - (void)showViewController:(UIViewController *)vc sender:(id)sender

    Parameters

    vc

    The view controller to display.

    sender

    The object that made the request to show the view controller.

    Discussion

    This method pushes a new view controller onto the navigation stack in a similar way as the pushViewController:animated: method. You can call this method directly if you want but typically this method is called from elsewhere in the view controller hierarchy when a new view controller needs to be shown.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    let UINavigationControllerHideShowBarDuration: CGFloat

    Objective-C

    extern const CGFloat UINavigationControllerHideShowBarDuration

    Constants

    • UINavigationControllerHideShowBarDuration

      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.