# SwiftUI Navigation with NavigationView and NavigationStack ## Pro Summary `NavigationStack` (iOS 16 / macOS 13+) models navigation as a stack of `Hashable` values: links push values, and `navigationDestination(for:)` maps each value type to a view, so deep links and state restoration come down to editing the path. `NavigationView` and the `NavigationLink(destination:isActive:)` / `(tag:selection:)` initializers are deprecated in favor of `NavigationStack`/`NavigationSplitView` with value-based links or `navigationDestination(isPresented:)`. Use a typed `[Route]` path when one enum covers every destination and `NavigationPath` when the stack holds mixed types; `NavigationPath.codable` supports restoration only when every element is `Codable`. ``` enum Route: Hashable { case detail(Int), settings } @State private var path: [Route] = [] NavigationStack(path: $path) { List(items) { item in NavigationLink(item.name, value: Route.detail(item.id)) } .navigationDestination(for: Route.self) { route in switch route { case .detail(let id): DetailView(id: id) case .settings: SettingsView() } } } // push: path.append(.settings) pop to root: path.removeAll() ``` Requires: iOS 16 / macOS 13 / tvOS 16 / watchOS 9 for `NavigationStack`, `NavigationPath`, `navigationDestination(for:destination:)` and `navigationDestination(isPresented:destination:)`; `navigationDestination(item:destination:)` needs iOS 17 / macOS 14 / tvOS 17 / watchOS 10. Gotchas: - `navigationDestination` has to be attached to a view inside the stack's content and outside lazy containers such as `List` or `LazyVStack` (Apple's docs say both). In a test on macOS 27, a destination attached to the `NavigationStack` itself never appeared when a value was pushed. - `NavigationView` is only soft-deprecated (`deprecated: 100000.0` in the SDK), so it compiles without warnings and keeps appearing in generated code, while `NavigationLink(destination:isActive:)` and `(tag:selection:)` are hard-deprecated at iOS 16 and do warn. - `NavigationPath.codable` is `nil` if any element isn't `Codable`, so restoring state quietly does nothing once a non-Codable value is on the path. - A typed `[Route]` path gives you exhaustive `switch` handling and simple equality checks for tests, while `NavigationPath` erases element types, so you can't inspect what's on the stack except through `count` and `isEmpty`. Primary sources: - [NavigationStack (Apple)](https://developer.apple.com/documentation/swiftui/navigationstack) - [navigationDestination(for:destination:) (Apple)](https://developer.apple.com/documentation/swiftui/view/navigationdestination(for:destination:)) - [Migrating to new navigation types (Apple)](https://developer.apple.com/documentation/swiftui/migrating-to-new-navigation-types) - [NavigationPath (Apple)](https://developer.apple.com/documentation/swiftui/navigationpath) Source: https://devdocs10.com/articles/swift/swift-navigation By Murat Bo · Updated 2026-10-17 · DevDocs10 (https://devdocs10.com) SwiftUI navigation is how users move from one screen to another in your app. In practice, this means placing content inside a navigation container, creating links to destination views, setting titles and toolbars, and sometimes controlling the navigation path in code. Understanding both `NavigationView` and `NavigationStack` matters because many older SwiftUI examples still use `NavigationView`, while modern apps should usually use `NavigationStack`. > **Quick answer:** Use `NavigationStack` for modern SwiftUI apps, especially on iOS 16 and later. `NavigationView` is the older API, still seen in existing code, but `NavigationStack` gives clearer and more flexible navigation, including path-based programmatic navigation. > **Difficulty:** Beginner > > **Helpful to know first:** You will understand this better if you know basic Swift syntax, how SwiftUI views are built with `body`, and simple state handling with `@State`. ## 1. What Is SwiftUI Navigation? SwiftUI navigation is the system that lets a user move deeper into app content and return again. A common example is tapping a row in a list to open a detail screen. - `NavigationView` is the older SwiftUI container for navigation-based layouts. - `NavigationStack` is the newer container that models navigation as a stack of destinations. - `NavigationLink` is used to push a destination view when the user taps something. - Navigation titles and toolbars help users understand where they are. - `NavigationStack` supports value-based and programmatic navigation more cleanly than `NavigationView`. Think of navigation as a stack of screens. The root screen is at the bottom. Each tap can push a new screen onto the stack, and the back button pops the top screen off. Because this topic naturally includes two related APIs, you should treat them differently: - Use `NavigationView` mainly to read or maintain older code. - Use `NavigationStack` in new apps when possible. ## 2. Why SwiftUI Navigation Matters Without navigation, most apps would be stuck on one screen. Real apps need users to move from summaries to details, from settings categories to specific settings, and from lists of items to full item pages. Navigation matters because it helps you: - Organize content into manageable screens. - Make large apps easier to understand. - Support standard iOS user expectations like back navigation and titles. - Handle deep links and programmatic screen changes more reliably. - Build list-detail interfaces, settings screens, and multistep flows. You should use SwiftUI navigation when a user moves between distinct screens. You should not use it for small visual changes that belong on the same screen, such as showing a loading spinner, expanding a section, or toggling a panel. ## 3. Basic Syntax The core idea is simple: wrap your content in a navigation container, then use `NavigationLink` to move to another view. ### Using NavigationStack This is the modern basic pattern. ```swift import SwiftUI struct HomeView: View { var body: some View { NavigationStack { VStack(spacing: 16) { Text("Home Screen") NavigationLink("Show Detail") { Text("Detail Screen") .navigationTitle("Detail") } } .padding() .navigationTitle("Home") } } } ``` This example creates a root screen with a title and a link. Tapping the link pushes the detail screen onto the navigation stack. ### Using NavigationView You will still see this in many tutorials and older projects. ```swift import SwiftUI struct LegacyHomeView: View { var body: some View { NavigationView { NavigationLink("Show Detail") { Text("Detail Screen") .navigationTitle("Detail") } .navigationTitle("Home") } } } ``` This older pattern still works in many cases, but it is not the preferred API for new SwiftUI navigation code. ### The core pieces - `NavigationStack` or `NavigationView`: the navigation container. - `NavigationLink`: the tappable element that pushes another view. - `navigationTitle()`: sets the title shown in the navigation bar. - `navigationDestination()`: maps values to destination views in value-based navigation. - `path`: an optional state value that lets code control the stack. ## 4. Step-by-Step Examples ### Example 1: Simple push navigation Start with the most common beginner case: one screen links to another. ```swift import SwiftUI struct SimpleNavigationView: View { var body: some View { NavigationStack { VStack(spacing: 20) { Text("Welcome to the app") NavigationLink("Go to Profile") { Text("Profile Screen") .navigationTitle("Profile") } } .padding() .navigationTitle("Home") } } } ``` This is the basic push-and-back experience. The system automatically shows a back button on the destination screen. ### Example 2: Navigation from a list Lists are one of the most common places to use navigation. ```swift import SwiftUI struct FruitListView: View { let fruits = ["Apple", "Banana", "Orange"] var body: some View { NavigationStack { List(fruits, id: \.self) { fruit in NavigationLink(fruit) { Text("You selected \(fruit)") .navigationTitle(fruit) } } .navigationTitle("Fruits") } } } ``` Here, each list row opens a matching detail screen. This pattern appears in contacts, messages, products, settings categories, and many other app features. ### Example 3: Value-based navigation with navigationDestination `NavigationStack` supports a more scalable style where you navigate using values instead of directly embedding each destination view inside every link. ```swift import SwiftUI struct DestinationListView: View { let numbers = [1, 2, 3] var body: some View { NavigationStack { List(numbers, id: \.self) { number in NavigationLink("Open item \(number)", value: number) } .navigationTitle("Numbers") .navigationDestination(for: Int.self) { number in Text("Detail for item \(number)") .navigationTitle("Item \(number)") } } } } ``` This approach is especially useful when many links of the same value type should go to the same kind of destination. ### Example 4: Programmatic navigation with a path Sometimes a button or app event should navigate without the user tapping a visible `NavigationLink`. A path lets you push values in code. ```swift import SwiftUI struct PathNavigationView: View { @State private var path = NavigationPath() var body: some View { NavigationStack(path: $path) { VStack(spacing: 16) { Text("Dashboard") Button("Open Settings") { path.append("settings") } } .navigationTitle("Dashboard") .navigationDestination(for: String.self) { route in if route == "settings" { Text("Settings Screen") .navigationTitle("Settings") } } } } } ``` This shows programmatic navigation. The button appends a value to the path, and SwiftUI uses the destination mapping to display the correct screen. ## 5. Practical Use Cases - A shopping app where a product list opens a product detail screen. - A settings interface where tapping a category opens a more specific settings page. - A mail or messaging app where selecting a conversation opens the full message thread. - A learning app where a course list opens lesson details and then quiz screens. - An admin dashboard where buttons trigger navigation to reports, users, or system settings. - A deep-link flow where the app opens directly to a specific screen by pushing values into a navigation path. ## 6. Common Mistakes ### Mistake 1: Using NavigationView for all new code Many beginners copy older examples and assume `NavigationView` is still the best default. It often works, but it does not provide the same modern, value-based navigation model as `NavigationStack`. **Problem:** This code uses the legacy navigation container in a new app, which can make future navigation logic harder to scale and maintain. ```swift NavigationView { List { NavigationLink("Profile") { Text("Profile Screen") } } } ``` **Fix:** Prefer `NavigationStack` in modern SwiftUI code unless you are maintaining older APIs or supporting code written around the older container. ```swift NavigationStack { List { NavigationLink("Profile") { Text("Profile Screen") } } } ``` The corrected version uses the modern navigation API and is better suited to current SwiftUI patterns. ### Mistake 2: Creating a NavigationLink without a navigation container `NavigationLink` needs to live inside a navigation container. Without `NavigationStack` or `NavigationView`, the navigation behavior will not work as expected. **Problem:** This link is not inside a navigation container, so the app cannot present it as part of a navigation stack. ```swift struct ContentView: View { var body: some View { NavigationLink("Open Detail") { Text("Detail") } } } ``` **Fix:** Place the link inside a navigation container so SwiftUI can manage the stack and back navigation. ```swift struct ContentView: View { var body: some View { NavigationStack { NavigationLink("Open Detail") { Text("Detail") } .navigationTitle("Home") } } } ``` The corrected version works because the link now belongs to a real navigation hierarchy. ### Mistake 3: Using value-based NavigationLink without a matching navigationDestination When you use `NavigationLink(value:)`, SwiftUI needs a matching `navigationDestination(for:)` for that value type. **Problem:** This code sends an `Int` value into the navigation stack, but no destination mapping tells SwiftUI how to display that type. ```swift NavigationStack { NavigationLink("Open Item", value: 5) } ``` **Fix:** Add a matching destination handler for the same value type, and attach it to a view inside the `NavigationStack`. ```swift NavigationStack { NavigationLink("Open Item", value: 5) .navigationTitle("Home") .navigationDestination(for: Int.self) { number in Text("Item \(number)") } } ``` The corrected version works because SwiftUI now knows how to turn an `Int` in the stack into a destination view. The modifier has to be inside the stack: if you attach it to the `NavigationStack` itself, the stack never finds it. ### Mistake 4: Putting the title on the wrong view Beginners often expect the navigation title to appear no matter where it is placed, but modifier placement matters in SwiftUI. **Problem:** This title is attached to a child view in a way that may not represent the intended screen title clearly. ```swift NavigationStack { VStack { Text("Dashboard") .navigationTitle("Home") } } ``` **Fix:** Attach the title to the main container view for that screen so the ownership is clearer and easier to maintain. ```swift NavigationStack { VStack { Text("Dashboard") } .navigationTitle("Home") } ``` The corrected version makes it clearer which screen owns the title and avoids confusion as the layout grows. ## 7. Best Practices ### Practice 1: Prefer NavigationStack for new apps The newer API is easier to scale, especially when you need value-based navigation or path control. ```swift // Preferred for modern SwiftUI navigation NavigationStack { Text("Home") } ``` This keeps your code aligned with current SwiftUI navigation patterns. ### Practice 2: Use value-based navigation for repeated destination types If many links open the same kind of destination, centralizing the destination mapping is cleaner than embedding destination views everywhere. ```swift NavigationStack { List(1...3, id: \.self) { item in NavigationLink("Item \(item)", value: item) } .navigationDestination(for: Int.self) { item in Text("Detail for \(item)") } } ``` This reduces repeated code and makes navigation rules easier to understand. ### Practice 3: Keep route values simple and predictable When using a path, simple route values are easier to test and reason about than unclear mixed data. ```swift @State private var path = NavigationPath() Button("Open Settings") { path.append("settings") } ``` Simple route values make programmatic navigation easier to debug. ### Practice 4: Set titles and toolbars per screen Each screen should clearly describe itself. Users rely on titles and navigation bar items to understand where they are. ```swift Text("Settings Screen") .navigationTitle("Settings") .toolbar { ToolbarItem(placement: .topBarTrailing) { Button("Save") { } } } ``` This makes the destination screen feel complete and easier to use. ## 8. Limitations and Edge Cases - `NavigationView` appears in older code and tutorials, so beginners often mix old and new navigation approaches in the same project. - `NavigationStack` is the modern API, but some older deployment targets or legacy app code may still rely on previous patterns. - Value-based navigation requires matching destination registrations for each type you push. - If navigation “does nothing,” check whether the link is inside a navigation container and whether the destination mapping exists. - Complex nested navigation can become hard to reason about if route values are inconsistent or spread across unrelated views. - Toolbar and title behavior depends on where modifiers are attached, so misplaced modifiers can make navigation feel broken even when the code compiles. - Using many inline destination closures can make large apps harder to maintain compared with centralized destination mapping. ## 9. NavigationView vs NavigationStack This comparison is important because developers frequently see both APIs and need to know which one to choose. | Feature | NavigationView | NavigationStack | | --- | --- | --- | | SwiftUI era | Older API | Modern API | | Recommended for new apps | No, usually not | Yes | | Value-based navigation | Limited pattern support | Built for it | | Programmatic path control | Less clear | Strong support | | Common in older tutorials | Very common | Increasingly common | ### When to use NavigationView - When maintaining older SwiftUI code that already uses it. - When reading legacy examples and translating them into your own code. - When you are not yet ready to refactor an existing project to `NavigationStack`. ### When to use NavigationStack - When starting a new SwiftUI app. - When you need value-based navigation with `navigationDestination`. - When your app needs programmatic navigation using a path. - When you want a clearer mental model of the current stack of screens. > A good rule is simple: learn both, but choose `NavigationStack` first when building modern SwiftUI apps. ## 10. Practical Mini Project This mini project builds a small app screen with a list of topics and a detail view for each one using modern value-based navigation. ```swift import SwiftUI struct TopicListView: View { let topics = ["Basics", "State", "Navigation", "Lists"] var body: some View { NavigationStack { List(topics, id: \.self) { topic in NavigationLink(topic, value: topic) } .navigationTitle("SwiftUI Topics") .navigationDestination(for: String.self) { topic in TopicDetailView(topic: topic) } } } } struct TopicDetailView: View { let topic: String var body: some View { VStack(spacing: 16) { Text("Topic: \(topic)") .font(.title2) Text("This screen shows details for the selected topic.") .multilineTextAlignment(.center) .padding(.horizontal) } .padding() .navigationTitle(topic) } } ``` This mini project demonstrates a realistic pattern: a root list pushes a typed value, and one destination rule maps that value to a detail view. This scales better than embedding a separate destination closure in every row for large lists. ## 11. Key Points - `NavigationStack` is the preferred SwiftUI navigation container for modern apps. - `NavigationView` is older and mainly important for existing code and tutorials. - `NavigationLink` pushes a destination view onto the stack. - Use `navigationTitle()` to label each screen clearly. - Use `NavigationLink(value:)` with `navigationDestination(for:)` for scalable value-based navigation. - A `NavigationPath` lets you control navigation in code. - If navigation is not working, check the container, destination mapping, and modifier placement. ## 12. Practice Exercise Build a small two-screen SwiftUI app that starts with a list of three cities. When the user taps a city, show a detail screen with the city name as the navigation title. - Use `NavigationStack`. - Show the cities in a `List`. - Use value-based navigation. - Create a separate detail view that accepts the city name. **Expected output:** A root screen titled `Cities` and a detail screen for the selected city. **Hint:** Use `NavigationLink(value:)` in the list and `navigationDestination(for:)` on the stack. ```swift import SwiftUI struct CityListView: View { let cities = ["London", "Tokyo", "Sydney"] var body: some View { NavigationStack { List(cities, id: \.self) { city in NavigationLink(city, value: city) } .navigationTitle("Cities") .navigationDestination(for: String.self) { city in CityDetailView(city: city) } } } } struct CityDetailView: View { let city: String var body: some View { VStack { Text("Welcome to \(city)") .font(.title) } .navigationTitle(city) } } ``` ## 13. Final Summary SwiftUI navigation gives your app structure by letting users move between screens in a familiar way. The two names you will see most often are `NavigationView` and `NavigationStack`. While both are important to recognize, modern SwiftUI development should usually start with `NavigationStack` because it offers a cleaner model, better value-based navigation, and stronger support for programmatic routes. In this article, you learned what SwiftUI navigation is, why it matters, how to create links and titles, how to use value-based destinations, how to control navigation with a path, and how to avoid common mistakes. A strong next step is to learn SwiftUI state management in more depth, especially `@State`, `@Binding`, and data flow patterns that drive navigation in larger apps. ## Where AI Coding Assistants Get This Wrong - Often suggested: Builds navigation from `NavigationView` plus `NavigationLink(destination:isActive:)` with a `@State var showDetail = false`. Instead: Use `NavigationStack` with `NavigationLink(value:)` + `navigationDestination(for:)`, drive it with a `path` binding, or use `navigationDestination(isPresented:)` for a boolean-triggered push. (The `isActive:` initializer has been deprecated since iOS 16 and `NavigationView` is deprecated in favor of `NavigationStack`/`NavigationSplitView`.) - Often suggested: Attaches `.navigationDestination(for:)` inside `List`/`ForEach` rows, or chains it after the closing brace of `NavigationStack { ... }`. Instead: Attach it once to the root content inside the stack, for example on the `List` itself, not on its rows. (Inside a lazy container the destination may not be loaded when the link fires, and outside the stack it is never consulted.) - Often suggested: Uses `.navigationBarTitle("Home")` and `.navigationBarItems(trailing:)`. Instead: Use `.navigationTitle("Home")` and `.toolbar { ToolbarItem(placement: .primaryAction) { ... } }`. (The SDK marks both old modifiers deprecated, renamed to `navigationTitle(_:)` and replaced by `toolbar(_:)`, and `navigationBarItems` is unavailable on macOS and watchOS.)