skip to content

In SwiftUI, how do NavigationLink(value:) and navigationDestination(for:destination:) work together to push a screen inside a NavigationStack?

level: juniorimportance: must knowfreq 76%

answer

  1. data first, view later
  2. matched by the value's type
  3. modifier inside the stack
  4. keep it out of lazy rows

basics

~10 s

NavigationLink(value:) presents a Hashable value; a navigationDestination(for:destination:) modifier inside the NavigationStack maps that value's type to a view, and the stack pushes that view. Attach the modifier outside lazy containers such as List.

solid answer

~40 s

Inside a `NavigationStack`, a link built with `NavigationLink(_:value:)` does not build its destination: it presents a `Hashable` value. Somewhere in the stack's hierarchy, `navigationDestination(for:destination:)` registers a closure for that value's type, and when the link fires the stack calls the closure and pushes the view it returns. One stack can carry several destination modifiers, one per data type, and SwiftUI matches each link by the type of its value. Apple's documentation says not to put the modifier inside a lazy container such as `List` or `LazyVStack`, because those create rows only when needed; attach it to the list itself so the stack can always see it. Separating the value from the view is what makes programmatic navigation possible, because the same values can live in a bound path that code reads and writes.

code

swift · 25 lines
swift
import SwiftUI

enum CatalogRoute: Hashable {
    case product(id: String)
}

struct CatalogView: View {
    let products: [Product]   // Product: Identifiable, with id and name

    var body: some View {
        NavigationStack {
            List(products) { product in
                NavigationLink(product.name, value: CatalogRoute.product(id: product.id))
            }
            // Outside the List, so the stack can always see it.
            .navigationDestination(for: CatalogRoute.self) { route in
                switch route {
                case .product(let id):
                    ProductDetailView(productID: id)
                }
            }
            .navigationTitle("Catalog")
        }
    }
}

go deeper

for a junior

Recall the two halves: a NavigationLink presents a Hashable value and navigationDestination(for:) turns that value's type into a screen, all inside a NavigationStack.

for a middle

Explain matching by type, why the modifier must sit outside lazy containers, and how value links differ from view-destination links in what a bound path records.

for a senior

Show you design route types deliberately: small enums of identifiers, destinations registered at the stack root, and no view-destination links on screens that must be deep-linked or restored.

for a principal

Frame value-based links as the precondition for routing, restoration and testing, and set the team rule that retires isActive links and NavigationView from the codebase.

## Two halves: a value and a destination SwiftUI's `NavigationStack` (iOS 16 and later) shows a **root view** and lets people push more views on top of it, removing them with the Back button or an edge swipe. The modern way to push is split into two declarations that meet at a **data type**: - **`NavigationLink(_:value:)`** or **`NavigationLink(value:label:)`** is the tappable row. It carries a value that must be `Hashable`, for example `CatalogRoute.product(id: "SKU-42")`. It does not know which view will appear. - **`navigationDestination(for:destination:)`** is a view modifier that says: "when the stack presents a value of type `D`, build this view from it". Its closure receives the value and returns the screen. When someone taps the link, the stack looks for a destination registered for the value's type, calls its closure, and pushes the result. Apple's own wording is that the stack "matches navigation links with navigation destinations based on their respective data types". ## How the matching works A single stack can present several kinds of data. You add one `navigationDestination(for:)` per type, for example one for `CatalogRoute` and one for `OrderRoute`, and each link finds its destination by the **type of its value**, not by declaration order and not by the label text. Two consequences follow: 1. **Route types should be specific.** If you push a bare `String`, every string pushed anywhere in that stack lands on the same destination. A small enum such as `CatalogRoute` keeps intent explicit and lets the destination `switch` over its cases. 2. **Values should be lightweight.** Apple's guide on the navigation stack advises against using model types as path elements; push an identifier and let the destination screen load the model. ## Where the modifier goes The destination is declared, not created per row, so its placement matters: - Put it **inside** the `NavigationStack`'s content, usually on the root view or on the `List` that holds the links. - Do **not** put it inside a lazy container (`List` rows, `LazyVStack`, `LazyVGrid`). Apple's documentation explains that these create child views only when needed to render on screen, so the stack might not see a destination attached to an off-screen row. - A link needs a navigation container above it. Apple notes that a link with no enclosing navigation structure typically appears disabled. - Destinations for every route type the stack can show are easiest to reason about when they all live at the stack's root; a destination declared on a pushed screen only exists once that screen is in the hierarchy. ## Value links versus view-destination links `NavigationLink` still has the older form that takes the destination view directly, `NavigationLink(destination:label:)`. It works inside a `NavigationStack`, but it behaves differently: | | `NavigationLink(value:)` + `navigationDestination(for:)` | `NavigationLink(destination:label:)` | |---|---|---| | What the link holds | a `Hashable` value | the destination view itself | | Recorded in a bound path | yes, the value is appended | no | | Restorable from code | yes, by writing the path | no, Apple says its state can't be restored programmatically | | Typical use | lists, deep links, restoration | a one-off push in a small screen | Apple's guide adds one interaction worth remembering: if code pushes a value while a view-destination screen is on top, SwiftUI pops all view destinations and then pushes the value's destination. For a push driven by state rather than a tap, SwiftUI also offers `navigationDestination(isPresented:destination:)` (iOS 16), which pushes one view while a `Bool` binding is true, and `navigationDestination(item:destination:)` (iOS 17), which pushes while an optional binding is non-nil and pops when you set it back to `nil`. Apple's documentation still says that, in general, binding a path to the stack is the preferred tool for programmatic navigation. ## What is deprecated - `NavigationView` is marked for deprecation in the iOS 27 SDK with the message "use NavigationStack or NavigationSplitView instead". - The `NavigationLink` initializers that take an `isActive:` binding, or `tag:` and `selection:`, were deprecated in iOS 16; the SDK points to `NavigationLink(value:label:)` or `navigationDestination(isPresented:destination:)` instead. ## Common mistakes 1. Attaching `navigationDestination(for:)` to each row inside a `List`. 2. Expecting the link's label or the modifier order to pick the destination. 3. Pushing whole model objects instead of identifiers. 4. Mixing in view-destination links on a screen that must be restored or deep-linked, then wondering why the bound path does not show them.

  • In SwiftUI, what happens if code appends a value to the bound path while a screen pushed with NavigationLink(destination:label:) is on top?
    Apple's navigation-stack guide says SwiftUI pops all the view-destination screens and then pushes the value's destination. View-destination pushes are never recorded in the bound path, so the stack keeps them above the value-based entries and drops them as soon as path-driven navigation takes over. On a screen that must be deep-linked or restored, use value links throughout.
  • When is navigationDestination(isPresented:destination:) a better fit than a value link?
    When one view should be pushed because some state became true, not because a row was tapped, for example a component that pushes its own detail after a check passes. It binds a `Bool` and pushes a single destination. Its iOS 17 sibling, `navigationDestination(item:destination:)`, pushes while an optional binding holds a value and pops when you set it to `nil`. For general programmatic navigation, Apple recommends binding a path to the stack.

  • Attach navigationDestination to every row inside the List
  • The link's label text decides which destination opens
  • A NavigationStack can have only one navigationDestination modifier
  • Wrap screens in NavigationView, it is the current container
  • Use NavigationLink with isActive for programmatic pushes