Contents

UINavigationController

A container view controller that defines a stack-based scheme for navigating hierarchical content.

Declaration

@MainActor class UINavigationController

Mentioned in

Overview

A navigation controller displays one view controller at a time. The ordered array of view controllers it manages forms the navigation stack. When you push a view controller onto the stack, it animates onscreen and covers the view controller that was previously on top.

A navigation interface reflects the structure of your app’s hierarchical data. For each level of the hierarchy, you provide a view controller that displays that level’s content. The following image shows an example in the Settings app. The root view controller displays top-level preference groups. Selecting a group reveals individual settings or additional subgroups. For every view except the root view controller, the navigation controller provides a Back button to return to the previous level.

[Image]

The first view controller in the navigation stack is the root view controller and represents the bottom of the stack. The last view controller is the topmost item on the stack, and represents the view controller that the system is currently displaying. You add and remove view controllers from the stack using show(_:sender:), pushViewController(_:animated:), popViewController(animated:), segues, or other methods provided by this class. People can also remove the topmost view controller by tapping the Back button or performing a swipe gesture. When long-pressed, the Back button presents a hierarchical list of all view controllers people can return to.

A navigation controller coordinates its behavior with its delegate object. The delegate object can respond to the pushing or popping of view controllers and provide custom animation transitions. Provide a delegate object that conforms to the UINavigationControllerDelegate protocol.

The following image shows the relationships between the navigation controller and the objects it manages. Use the specified properties of the navigation controller to access these objects.

[Image]

Manage the navigation bar and toolbar

A navigation controller embeds the content of other view controllers in its own view, and it manages the creation, configuration, and display of its bars.

The following image shows how these views combine to form the navigation interface.

[Image]

Prefer using the provided bars and manage their content with navigationItem and toolbarItems. Don’t change the navigation bar’s frame, bounds, or alpha values directly.

If you subclass UINavigationBar, initialize your navigation controller using the init(navigationBarClass:toolbarClass:) method. To hide or show the navigation bar, use the isNavigationBarHidden property or setNavigationBarHidden(_:animated:) method.

Update navigation controls

As people navigate your app, the navigation controller updates its bars. The top-level view controller on the navigation stack defines its navigation and toolbar items. Navigation controllers adapt their layout based on the current traitCollection.

Horizontal and vertical axes

In a horizontal layout, navigation controls appear across the top of the view and toolbars appear along the bottom. On iPhone Duo, the system considers whether your content is better suited for a vertical or horizontal axis. On a vertical axis, navigation controls and toolbar items, along with tab bar items, consolidate into a shared region as a unified vertical stack.

The following sections relate to navigation bar items on a horizontal axis. Designing for the horizontal axis allows your app to adapt for the vertical axis in ways people expect. In most cases, when moved to the vertical axis, horizontal bars effectively rotate 90 degrees to stack their content with the leading item at the top. For more detail on how bar items adjust to the vertical axis, watch Raise the bar with iPhone Duo. For design guidance, see Vertical controls in Human Interface Guidelines > Designing for iPhone Duo.

Leading items

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

  • If the new top-level view controller defines leading item groups, the navigation bar displays those groups. To specify leading item groups, set the leadingItemGroups property of the view controller’s navigation item.

  • If leftItemsSupplementBackButton is true, leading items display in addition to the Back button.

  • If the top-level view controller doesn’t have a custom leading item, but the navigation item of the previous view controller has an object in its backBarButtonItem property, the navigation bar displays that item.

  • If leading items aren’t specified by either of the view controllers, the system uses a default Back button that displays a back image.

When a Back button’s title is too long to fit, the navigation bar displays a back image, but only when the previous view controller provides the Back button. If the new top-level view controller instead has a leading item, the navigation bar doesn’t change that item’s title. If the item’s title is too long to fit, the navigation bar places it in the menu of the overflow item on the trailing edge.

Center items

The navigation controller updates the center 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 you don’t set a custom title view, 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. If you want to change the appearance of the title, such as its font or color, use attributedTitle.

  • If you set style to UINavigationItem.ItemStyle.browser or UINavigationItem.ItemStyle.editor, the navigation item’s title appears on the leading side of the navigation bar, and center items appear in the center of the bar when space is available. To specify center item groups, set the centerItemGroups property of the view controller’s navigation item.

Trailing items

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

  • If the new top-level view controller defines trailing item groups, the navigation bar displays those groups. To specify trailing item groups, set the trailingItemGroups property of the view controller’s navigation item.

  • If the view controller has no custom trailing items, the trailing edge of the navigation bar is empty.

  • If leading or center items don’t fit, the navigation bar moves them into an overflow item on the trailing edge, whether or not the view controller has custom trailing items. The overflow item is a button with an ellipsis that opens a menu of the items that moved.

Display a toolbar

A navigation controller object manages an optional toolbar in its view hierarchy. When the navigation controller displays this toolbar, the toolbar obtains its current 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 toolbar is hidden by default. To hide or show it, use the isToolbarHidden property or setToolbarHidden(_:animated:) method of your navigation controller object. Prefer the provided toolbar so the system can decide whether a vertical or horizontal axis better suits your content. To use a custom UIToolbar subclass, initialize the navigation controller using the init(navigationBarClass:toolbarClass:) method.

Handle orientation and presentation context

A navigation controller supports the following behaviors for its interface:

Supported interface orientations

A navigation controller object doesn’t consult the view controllers on its navigation stack when determining the supported interface orientations. On iPhone and the outer display of iPhone Duo, a navigation controller supports all orientations except portrait upside-down. On iPad and the inner display of iPhone Duo, a navigation controller supports all orientations. If the navigation controller has a delegate object, the delegate can specify a different set of supported orientations using the navigationControllerSupportedInterfaceOrientations(_:) method.

Presentation context

A navigation controller defines the presentation context for modally presented view controllers. When modalPresentationStyle is UIModalPresentationStyle.currentContext or UIModalPresentationStyle.overCurrentContext, modal presentations from the view controllers in the navigation stack cover the entire navigation interface.

Preserve navigation state

When you assign a value to a navigation controller’s restorationIdentifier property, it attempts to preserve itself and the contained 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, the navigation controller restores the preserved view controllers to the navigation stack in the same order it preserved them.

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

For more information about how state preservation and restoration work, see Preserving your app’s UI across launches.

Topics

Creating a navigation controller

Customizing the navigation interface behavior

Accessing items on the navigation stack

Pushing and popping stack items

Configuring navigation bars

Configuring custom toolbars

Hiding the navigation bar

Displaying view controllers

See Also

Container view controllers