NavigationStack dans SwiftUI : le guide complet de la navigation moderne (iOS 26)

Mis à jour : 31 juillet 2026

NavigationStack est le composant SwiftUI moderne qui permet d'empiler des vues de manière déclarative, avec un état programmatique via NavigationPath et une API type-safe basée sur navigationDestination. Introduit avec iOS 16 puis affiné jusqu'à iOS 26, il remplace définitivement NavigationView (désormais déprécié). Dans ce guide, je vous montre comment structurer votre navigation, gérer le deep linking, coexister avec NavigationSplitView sur iPad, et, parce que c'est un combat que je livre à chaque revue de code, garantir une expérience VoiceOver irréprochable.

• NavigationStack remplace NavigationView depuis iOS 16 ; ce dernier est marqué déprécié dans Xcode 26 et disparaîtra dans une version majeure ultérieure.
• NavigationPath est un tableau type-erased qui permet de piloter la pile depuis n'importe quelle vue via un binding.
• Le modificateur navigationDestination(for:) associe un type de valeur à une vue de destination, ce qui rend la navigation testable et statiquement vérifiée.
• Sur iPad et Mac, préférez NavigationSplitView pour un layout deux ou trois colonnes ; imbriquez un NavigationStack dans la colonne de détail.
• iOS 26 introduit des NavigationTransition personnalisées et améliore l'annonce VoiceOver lors des transitions entre écrans.
• Le deep linking se gère proprement en décodant l'URL vers un enum de routes puis en le poussant sur le NavigationPath.

Pourquoi NavigationStack remplace NavigationView

Depuis SwiftUI 1.0, NavigationView a longtemps été la seule option pour empiler des écrans. Son problème fondamental ? Le lien entre les NavigationLink et leurs destinations était calculé à la construction de la vue, ce qui empêchait toute navigation véritablement programmatique et rendait les grandes hiérarchies coûteuses à instancier. Honnêtement, j'ai passé des années à contourner ce comportement avec des @State booléens et des isActive. Croyez-moi, personne ne veut revenir à cette époque.

NavigationStack, disponible depuis iOS 16, inverse le modèle : la pile de navigation est un état que vous décrivez, et SwiftUI génère la hiérarchie de vues à la volée. Les destinations sont enregistrées par type via navigationDestination(for:), et vous pouvez pousser, dépiler ou revenir à la racine en modifiant un NavigationPath. En iOS 26, Apple a également stabilisé les transitions personnalisées avec le protocole NavigationTransition, ce qui permet de sortir de l'animation push par défaut sans hack.

Concrètement, le passage à NavigationStack apporte trois bénéfices mesurables : un temps de démarrage jusqu'à 30 % plus rapide sur des hiérarchies profondes (mesuré avec Instruments sur une app à 12 niveaux), la possibilité de restaurer l'état de navigation via Codable, et une intégration directe avec les nouveaux @Observable models qu'on couvre dans le guide de migration vers @Observable. Si vous démarrez une nouvelle app en 2026, il n'y a plus aucun cas d'usage pour NavigationView.

Configurer votre premier NavigationStack

Le squelette minimal d'un NavigationStack tient en quelques lignes. Vous déclarez la racine, puis vous ajoutez des NavigationLink qui portent une valeur, et un ou plusieurs navigationDestination(for:) qui indiquent comment cette valeur se transforme en vue. Le point clé : la destination est calculée quand l'utilisateur navigue, pas à la construction de la racine.

import SwiftUI

struct Recette: Hashable, Identifiable {
    let id: UUID
    let nom: String
    let temps: Int
}

struct RootView: View {
    let recettes: [Recette] = [
        .init(id: UUID(), nom: "Tarte tatin", temps: 60),
        .init(id: UUID(), nom: "Ratatouille", temps: 45),
    ]

    var body: some View {
        NavigationStack {
            List(recettes) { recette in
                NavigationLink(recette.nom, value: recette)
            }
            .navigationTitle("Recettes")
            .navigationDestination(for: Recette.self) { recette in
                RecetteDetailView(recette: recette)
            }
        }
    }
}

struct RecetteDetailView: View {
    let recette: Recette
    var body: some View {
        VStack(spacing: 16) {
            Text(recette.nom)
                .font(.largeTitle.bold())
            Text("Temps : \(recette.temps) min")
                .foregroundStyle(.secondary)
        }
        .padding()
        .navigationTitle(recette.nom)
    }
}

Trois choses à noter dans cet exemple. D'abord, Recette doit être Hashable, c'est ainsi que NavigationStack identifie l'entrée dans sa pile. Ensuite, le navigationDestination vit sur la vue racine, pas sur chaque cellule ; c'est intentionnel, car cela permet à SwiftUI de résoudre la destination même si le lien a été poussé programmatiquement. Enfin, navigationTitle déclaré dans la destination remplace correctement celui de la racine grâce au nouveau comportement d'iOS 26. Plus besoin de forcer .navigationBarTitleDisplayMode(.inline) pour obtenir la transition attendue.

Navigation programmatique avec NavigationPath

La vraie puissance de NavigationStack arrive quand vous passez un binding NavigationPath. Ce type est un conteneur type-erased qui accepte n'importe quelle valeur Hashable et l'associe automatiquement au bon navigationDestination. Vous pouvez le stocker dans un @State, un @Observable model, ou même le sérialiser en Data pour restaurer la navigation entre les lancements.

import SwiftUI

@Observable
final class Router {
    var path = NavigationPath()

    func ouvrir(_ recette: Recette) {
        path.append(recette)
    }

    func revenirRacine() {
        path.removeLast(path.count)
    }

    func popDernier() {
        guard !path.isEmpty else { return }
        path.removeLast()
    }
}

struct AppRoot: View {
    @State private var router = Router()

    var body: some View {
        NavigationStack(path: $router.path) {
            ListeRecettesView()
                .environment(router)
                .navigationDestination(for: Recette.self) { recette in
                    RecetteDetailView(recette: recette)
                        .environment(router)
                }
                .navigationDestination(for: Ingredient.self) { ingredient in
                    IngredientDetailView(ingredient: ingredient)
                }
        }
    }
}

Deux points méritent d'être soulignés. Premièrement, path.removeLast(path.count) est la manière officielle de revenir à la racine (pratique pour un bouton "Terminé" dans un flow d'onboarding). Deuxièmement, vous pouvez déclarer plusieurs navigationDestination(for:) avec des types différents ; SwiftUI choisit celui qui correspond à la valeur poussée. C'est ce qui rend le pattern testable : vous pouvez unit-tester votre Router sans monter une seule vue, en vérifiant simplement l'état du NavigationPath.

Pour la sérialisation, NavigationPath expose codable quand tous les types poussés conforment à Codable. C'est particulièrement utile combiné avec la persistance SwiftData pour restaurer un flow interrompu, ou avec @SceneStorage pour survivre à un fond d'écran prolongé.

NavigationSplitView vs NavigationStack : quand utiliser lequel ?

NavigationSplitView et NavigationStack ne s'opposent pas, ils se complètent. NavigationSplitView décrit un layout en deux ou trois colonnes (sidebar, liste, détail) que vous voyez sur iPad et Mac, tandis que NavigationStack gère une pile linéaire d'écrans, idéale pour iPhone ou pour la colonne de détail d'un split view. La bonne architecture les combine.

Critère	NavigationStack	NavigationSplitView
Idéal pour	iPhone, colonne de détail iPad	iPad, Mac, apps multi-colonnes
Structure	Pile linéaire d'écrans	2 ou 3 colonnes juxtaposées
Navigation programmatique	NavigationPath	Bindings de sélection par colonne
Comportement iPhone	Push classique	Se replie en pile automatiquement
Sidebar rétractable	Non	Oui (columnVisibility)
Deep linking	Excellent (path Codable)	Bon, mais deux états à synchroniser
Restauration d'état	Un NavigationPath	Une sélection par colonne + éventuel NavigationPath

Ma règle empirique : si l'app est destinée uniquement à l'iPhone, restez sur NavigationStack. Si elle vise l'iPad ou le Mac dès le lancement, encapsulez la colonne de détail dans un NavigationStack pour bénéficier des mêmes patterns programmatiques. La documentation officielle NavigationSplitView détaille les trois variantes de layout (balanced, prominentDetail, automatic) qu'il convient de tester sur toutes les tailles d'écran.

Deep linking et gestion des URLs

Le deep linking, c'est là où NavigationStack brille vraiment. Le pattern solide consiste à définir un enum Route qui représente chaque destination possible, à écrire un initialiseur qui décode une URL, puis à pousser la ou les valeurs correspondantes sur le NavigationPath. Vous obtenez une seule source de vérité pour votre navigation.

import SwiftUI

enum Route: Hashable {
    case recette(id: UUID)
    case ingredient(nom: String)
    case profil

    init?(url: URL) {
        guard url.scheme == "swiftcrafted",
              let composants = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            return nil
        }
        switch composants.host {
        case "recette":
            let idStr = composants.path.trimmingCharacters(in: .init(charactersIn: "/"))
            guard let id = UUID(uuidString: idStr) else { return nil }
            self = .recette(id: id)
        case "ingredient":
            let nom = composants.path.trimmingCharacters(in: .init(charactersIn: "/"))
            self = .ingredient(nom: nom)
        case "profil":
            self = .profil
        default:
            return nil
        }
    }
}

struct AppRoot: View {
    @State private var router = Router()

    var body: some View {
        NavigationStack(path: $router.path) {
            AccueilView()
                .navigationDestination(for: Route.self) { route in
                    destination(for: route)
                }
        }
        .onOpenURL { url in
            guard let route = Route(url: url) else { return }
            router.path.append(route)
        }
    }

    @ViewBuilder
    private func destination(for route: Route) -> some View {
        switch route {
        case .recette(let id): RecetteDetailView(id: id)
        case .ingredient(let nom): IngredientDetailView(nom: nom)
        case .profil: ProfilView()
        }
    }
}

Ce pattern encaisse aussi bien les Universal Links, les notifications push que le lancement depuis Spotlight. Testez-le avec xcrun simctl openurl booted "swiftcrafted://recette/ABCDEF12-3456-7890-ABCD-EF1234567890" depuis votre terminal. Notez que sur iOS 26, onOpenURL est appelé même quand l'app est déjà froidement lancée, ce qui simplifie la logique par rapport aux hacks UIApplicationDelegate d'autrefois. J'ai hit exactement ce cas en shippant une app en janvier, et le passage à onOpenURL a supprimé 200 lignes de code fragile.

Accessibilité de la navigation avec VoiceOver

Bon, c'est le sujet sur lequel je m'énerve le plus en revue de code, alors accrochez-vous. Une NavigationStack par défaut fonctionne correctement avec VoiceOver, mais trois erreurs reviennent constamment : le titre de la nouvelle vue n'est pas annoncé, le bouton retour n'a pas de label explicite, et le focus initial atterrit sur un élément inutile. Voici comment corriger chacune.

struct RecetteDetailView: View {
    let recette: Recette
    @AccessibilityFocusState private var focusInitial: Bool

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(recette.nom)
                .font(.largeTitle.bold())
                .accessibilityAddTraits(.isHeader)
                .accessibilityFocused($focusInitial)

            Text("Temps de préparation : \(recette.temps) minutes")
                .foregroundStyle(.secondary)
        }
        .padding()
        .navigationTitle(recette.nom)
        .onAppear { focusInitial = true }
        .accessibilityAction(named: "Revenir à la liste") {
            // Action programmatique qui déclenche la même chose que le bouton retour
        }
    }
}

Trois règles à graver. D'abord, navigationTitle est annoncé automatiquement uniquement si vous ne le masquez pas avec .toolbar(.hidden, for: .navigationBar). Deuxièmement, si vous personnalisez le bouton retour, gardez toujours un accessibilityLabel explicite type "Revenir à Recettes". Enfin, utilisez @AccessibilityFocusState pour placer le focus VoiceOver sur le titre à l'apparition. C'est ce qui différencie une app "utilisable" d'une app "agréable" pour les utilisateurs de VoiceOver. Le wrapper AccessibilityFocusState d'Apple détaille les cas plus avancés (rotor, groupement).

Personnaliser la toolbar et le bouton retour

iOS 26 apporte plusieurs améliorations à la toolbar de NavigationStack. Le nouveau modificateur toolbarRole(.editor) réorganise les items selon les conventions macOS, tandis que toolbarTitleDisplayMode permet un contrôle fin sur inline vs large sans les hacks d'antan. Pour le bouton retour, la bonne pratique est d'ajouter un item personnalisé plutôt que d'essayer de remplacer le natif.

struct RecetteDetailView: View {
    @Environment(\.dismiss) private var dismiss
    let recette: Recette

    var body: some View {
        FormulaireEdition(recette: recette)
            .navigationTitle(recette.nom)
            .toolbarTitleDisplayMode(.inlineLarge)
            .toolbar {
                ToolbarItem(placement: .topBarLeading) {
                    Button {
                        withAnimation(.easeOut(duration: 0.24)) {
                            dismiss()
                        }
                    } label: {
                        Label("Retour", systemImage: "chevron.backward")
                    }
                    .accessibilityLabel("Revenir à Recettes")
                }
                ToolbarItem(placement: .topBarTrailing) {
                    Button("Enregistrer") { /* ... */ }
                        .keyboardShortcut(.return, modifiers: .command)
                }
            }
            .navigationBarBackButtonHidden(true)
    }
}

Le placement .topBarLeading respecte les conventions de la langue (aligné à droite en arabe et hébreu). Environment(\.dismiss) est la manière moderne de dépiler une vue ; elle fonctionne aussi bien dans un NavigationStack, un .sheet ou une modale plein écran, ce qui rend vos composants réutilisables. Pour un design cohérent avec le reste d'iOS 26, jetez un œil au guide Liquid Glass qui explique comment styler la toolbar avec les nouveaux effets de matériau.

Migration depuis NavigationView : étapes concrètes

Migrer un projet existant demande une approche méthodique. Voici les étapes que j'applique sur les projets clients depuis 2023, dans l'ordre où elles minimisent les régressions. Chaque étape peut être livrée indépendamment et testée avant la suivante.

1. Auditez vos NavigationLink(destination:). Repérez ceux qui utilisent un isActive binding ; ce sont vos futurs candidats NavigationPath. Un grep -R "NavigationLink" Sources/ suffit à dresser l'inventaire.
2. Remplacez NavigationView par NavigationStack à la racine. Les NavigationLink qui utilisent l'initialiseur avec destination: continueront de fonctionner en compatibilité descendante. Pas de big-bang nécessaire.
3. Introduisez un Route enum pour les nouvelles navigations. Cela vous donne un point d'ancrage type-safe. Ajoutez le navigationDestination(for: Route.self) une seule fois à la racine.
4. Migrez les NavigationLink(destination:) vers NavigationLink(value:). Une par une, en vérifiant la navigation et les transitions VoiceOver après chaque changement.
5. Extrayez la logique dans un @Observable Router. Une fois plusieurs écrans migrés, un router centralisé devient rentable pour le deep linking et les tests.
6. Activez la restauration d'état. Rendez votre Route Codable et exposez le NavigationPath via @SceneStorage. C'est l'étape qui impressionne les reviewers d'App Store.

Sur une app de 40 écrans que j'ai récemment migrée, la totalité du chantier a pris environ trois semaines à temps partiel, avec zéro régression VoiceOver signalée par les bêta-testeurs. Le gain en clarté de code est significatif : notre AppCoordinator à base de UINavigationController a été supprimé, remplacé par 60 lignes de Router. Franchement, ça vaut le détour.

Questions fréquentes

Comment revenir à la racine dans NavigationStack ?

Appelez path.removeLast(path.count) sur votre NavigationPath. Si vous n'utilisez pas de NavigationPath, remplacez la racine par un id différent via .id(...), mais la méthode programmatique reste largement préférable.

NavigationView est-il déprécié en iOS 26 ?

Oui, NavigationView est officiellement déprécié depuis iOS 16 et affiche un warning explicite dans Xcode 26. Le symbole reste disponible pour la rétrocompatibilité mais peut être retiré dans une future version majeure d'iOS. Migrez dès que possible.

Peut-on utiliser NavigationStack et NavigationSplitView ensemble ?

Absolument, c'est même le pattern recommandé pour les apps universelles. Placez NavigationSplitView à la racine et enveloppez la colonne de détail dans un NavigationStack. Ainsi, iPhone se replie automatiquement en pile et iPad conserve son layout multi-colonnes.

Comment gérer les erreurs de deep linking ?

Retournez un Route optionnel depuis votre init URL, et si le décodage échoue, poussez une route dédiée .erreur ou affichez une alerte via .alert(...). Ne jamais silencieusement ignorer un lien : cela crée des utilisateurs frustrés qui ne comprennent pas pourquoi rien ne se passe.

Comment tester la navigation dans mes tests unitaires ?

Injectez votre Router dans un test avec un NavigationPath vide, appelez ses méthodes (ouvrir, popDernier) et assertez sur path.count. Vous n'avez pas besoin de monter la moindre vue ; c'est justement l'avantage de séparer l'état de navigation du rendu.