Structure

NavigationView

A container for view navigation along with a (optional) navigation bar.

---

Declaration

struct NavigationView<Content> : View where Content : View

---

Overview

NavigationView is a container that adds stack-based navigation to a view, along with a (optional) navigation bar.

Setting up a navigation stack

A navigation stack is set up simply by wrapping your view in a NavigationView:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            Text("Hello Bananas🍌🍌")
        }
    }
}

A navigation bar is added by default. The navigation bar can be hidden via navigationBarHidden(_:).

Adding a navigation title

Use View/navigationTitle(_:)-5ad18 to add a title to the navigation bar within your NavigationView:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            Text("Hello Bananas🍌🍌")
                .navigationTitle("Home")
        }
    }
}

navigationTitle(_:) is only available on iOS 14 and higher. If your application targets iOS 13, please use navigationBarTitle(_:).

Setting the navigation title display mode

The display mode of a navigation bar title can be controlled via navigationBarTitleDisplayMode(_:). There are two main display modes:

• NavigationBarItem.TitleDisplayMode.inline
• NavigationBarItem.TitleDisplayMode.large

An automatic mode is also present, and represents the system default.

The following example forces a large navigation title:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            Text("Hello Bananas🍌🍌")
                .navigationTitle("Home")
                .navigationBarTitleDisplayMode(.large)
        }
    }
}

Navigating to a view

Use NavigationLink to add a button that pushes a new view onto the navigation stack.

For example, the following presents BananasView when the link "I want bananas!" is pressed:

struct ExampleView: View {
    struct BananasView: View {
        var body: some View {
            Text("Bananas")
                .navigationTitle("🍌🍌")
        }
    }

    var body: some View {
        NavigationView {
            NavigationLink(destination: BananasView()) {
                Text("I want bananas!")
            }
        }
    }
}

Hiding the navigation bar

The navigation bar is on by default within a NavigationView. It can be hidden using navigationBarHidden(_:).

For example:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            Text("Hello Bananas🍌🍌")
                .navigationBarHidden(true)
        }
    }
}

Note that the navigation bar can be unhidden by child views. navigationBarHidden(_:) is a preference value, and uses the value proposed by the deepest view in the hierarchy as its active value. This is to say, a screen with the navigation bar hidden can push a screen that unhides the bar.

For example, navigating to SecondScreen in the following unhides the bar:

struct ExampleView: View {
    struct SecondScreen: View {
        var body: some View {
            Text("Bananas🍌🍌")
                .navigationTitle("Second Screen")
                .navigationBarHidden(false)
        }
    }

    var body: some View {
        NavigationView {
            VStack {
                Text("Hello Bananas🍌🍌")

                NavigationLink(destination: SecondScreen()) {
                    Text("Take me to the second screen!")
                }
            }
            .navigationBarHidden(true)
        }
    }
}

And popping SecondScreen (or navigating back) hides it again, as SecondScreen is removed from the view hierarchy, leaving ExampleView as the deepest view in the hierarchy - which has hidden the navigation bar.

Adding navigation bar items

Use navigationBarItems(leading:trailing:) to add items to a navigation bar's leading and trailing areas.

For example, the following adds "🍌🍌" to the leading area, and "🍏🍏" to the trailing area:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            Text("Hello Bananas🍌🍌")
                .navigationBarItems(leading: Text("🍌🍌"), trailing: Text("🍏🍏"))
        }
    }
}

Styling a navigation view

Use navigationViewStyle(_:) to style a navigation view.

For example, the following forces a stack-based navigation style, overriding the default double-column style on Mac Catalyst:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            NavigationLink("Hello Bananas", destination: Text("🍌🍌"))
        }
        .navigationViewStyle(StackNavigationViewStyle())
    }
}

And the following forces a double-column navigation style, overriding the default stack-based navigation style on iPadOS:

struct ExampleView: View {
    var body: some View {
        NavigationView {
            NavigationLink("Hello Bananas", destination: Text("🍌🍌"))
        }
        .navigationViewStyle(DoubleColumnNavigationViewStyle())
    }
}

Handling selection

NavigationLink provides the ability to observe and/or set the active navigation selection via its initializer init(destination:tag:selection:label:).

For example:

struct ExampleView: View {
    enum NavigationItem {
        case bananas
        case apples
        case peaches
    }

    @State var navigatedItem: NavigationItem? = .bananas

    var body: some View {
        NavigationView {
            NavigationLink(
                destination: Text("🍏🍏"),
                tag: NavigationItem.apples,
                selection: $navigatedItem
            ) {
                Text("Apples")
            }

            NavigationLink(
                destination: Text("🍌🍌"),
                tag: NavigationItem.bananas,
                selection: $navigatedItem
            ) {
                Text("Bananas")
            }

            NavigationLink(
                destination: Text("🍑🍑"),
                tag: NavigationItem.peaches,
                selection: $navigatedItem
            ) {
                Text("Peaches")
            }
        }
    }
}

In the example above, the navigation selection is written to a state variable, navigatedItem. navigatedItem is an optional, because it is possible for the screen to not be navigated to any particular screen (i.e. be at the root view containing the 3 navigation links).

See ToolbarItem for more on what can be placed in the navigation bar.

Availability

iOS 13.0+

macOS 10.15+

tvOS 13.0+

watchOS 7.0+

Topics

---

Type Alias

Body The type of view representing the body of this view.

---

Initializer

init(content:) Creates a navigation view from a view builder of content.