SwiftUIFlow: Type-Safe Coordinator Navigation for SwiftUI

Ioannis Platsis — Thu, 22 Jan 2026 15:05:47 +0000

You're building a SwiftUI app.
User navigates: Home → Product Details → Reviews → User Profile.

Now they tap "Message this user"—a feature that lives in a completely different part of your app.

How do you navigate there cleanly?

Most solutions involve either tight coupling, global state, or writing hundreds of lines of custom coordination code.

There's a better way.

At a Glance

SwiftUIFlow is a type-safe coordinator navigation framework for SwiftUI that makes complex navigation simple.

What it does:

Navigate anywhere from anywhere: coordinator.navigate(to: .route)
Smart automatic navigation — backward detection, modal dismissal, tab switching
Context-preserving deep links — don't lose user state
Type-safe enum routes — compiler catches mistakes
50% less boilerplate with FlowOrchestrator

iOS 17+ | MIT License | Production-ready

🔗 GitHub | Documentation | Example
App

The Problem

SwiftUI's NavigationStack handles basic navigation well. But real apps need:

❌ Cross-feature navigation — Settings (Tab 4) → Profile (Tab 1)?
❌ Deep linking without state loss — Push notification shouldn't kill user's upload progress
❌ Modals with deep linking — Navigate to Settings → Privacy → Delete Account from notification
❌ Type safety — String routes break at runtime

Traditional solutions: Pass coordinators through views (tight coupling), global state (@EnvironmentObject everywhere), or custom routing infrastructure
(hundreds of lines).

What if you could navigate to any route, from anywhere, with one line of code — and the framework handled everything?

Meet SwiftUIFlow

coordinator.navigate(to: .profile(userId: "alice"))

That's it. From anywhere in your app, navigate to any route.

The framework automatically:

✅ Finds which coordinator handles the route
✅ Switches tabs if needed
✅ Dismisses modals if needed
✅ Detects backward navigation (auto-pops)
✅ Cleans up navigation state
✅ Executes the navigation

Zero configuration. Zero boilerplate. It just works.

Key Features

1. Universal Navigate API ⭐⭐

Navigate from anywhere to anywhere. The framework finds the right path.

The scenario:
User is deep in Tab 3. You need them in Tab 1's profile screen.

  coordinator.navigate(to: .profile(userId: "alice"))
  // Framework handles tab switching, coordinator lookup, navigation

How it works: Routes bubble through the coordinator hierarchy. Each coordinator checks: "Can I handle this? Can my children? Can my parent?" The framework finds the right coordinator automatically.

Deep linking becomes trivial:

  func handleDeepLink(url: URL) {
      let route = DeepLinkParser.parse(url)
      appCoordinator.navigate(to: route) // Done!
  }

2. Smart Automatic Navigation ⭐⭐

The framework watches your navigation state and does the right thing automatically.

Automatic Backward Detection:

  // Current stack: [Home, Settings, Profile]
  coordinator.navigate(to: .settings)
  // Framework detects .settings is already in stack
  // Automatically pops back to Settings (no duplicate!)

You wrote zero code for this. It just works.

Automatic Modal Dismissal:

  // Tab 1 has a modal open
  coordinator.navigate(to: Tab2Route.settings)
  // Framework automatically:
  // 1. Dismisses the modal
  // 2. Switches to Tab 2
  // 3. Navigates to Settings

Idempotency:

  coordinator.navigate(to: .profile)
  coordinator.navigate(to: .profile) // Already there, skips

No navigation loops. No duplicate screens. The framework prevents common bugs automatically.

Automatic Back Button Management:

  // Framework provides environment values automatically
  @Environment(\.navigationBackAction) var backAction
  @Environment(\.canNavigateBack) var canNavigateBack

  // Back button appears automatically for:
  // - Pushed coordinators
  // - Modal presentations
  // - Detour presentations

  // Tapping back does the right thing automatically:
  // - Push? Pops from stack
  // - Modal? Dismisses modal
  // - Detour? Dismisses detour

No manual configuration. Framework provides the correct action for every context.

Two-Phase Navigation (Validation Before Execution With Error Handling):

  coordinator.navigate(to: .invalidRoute)
  // Framework validates the entire navigation path FIRST
  // If any coordinator can't handle it: reports error immediately
  // If valid: executes the navigation
  // No partial navigation failures!

This prevents bugs where navigation half-succeeds then crashes.

3. Context-Preserving Deep Links (Detours) ⭐⭐

The problem:

User state: Tab 3 → Settings → Edit Profile → Uploading Photo (80% done)
Push notification: "New message from Alice"

Traditional approach: Navigate to Messages → Upload lost → User frustrated 😤

SwiftUIFlow's solution:

  let messagesCoord = MessagesCoordinator(messageId: "123")
  coordinator.presentDetour(messagesCoord, presenting: .messages)

What happens:

Message screen slides in full-screen
User reads message
User dismisses
Back to Settings → Edit Profile → Upload still at 80%! ✨

The underlying navigation state is completely preserved. Modals, stacks, uploads — everything stays intact.

Uses .fullScreenCover under the hood but with complete coordinator lifecycle management.

Perfect for:

Push notifications (don't lose user's place)
Error flows (show error, return to working state)
Onboarding overlays (dismiss back to app)

4. Type-Safe Enum Routes ⭐

Before (string-based routes):

  navigationPath.append("profile") // Typo? Runtime crash 💥

After (enum routes):

enum AppRoute: Route {
      case home
      case profile(userId: String)
      case settings

      var identifier: String {
          switch self {
          case .home: return "home"
          case .profile(let id): return "profile-\(id)"
          case .settings: return "settings"
          }
      }
  }

  coordinator.navigate(to: .profle) // Typo = compile error ✅
  coordinator.navigate(to: .profile) // Missing userId? = compile error ✅

Benefits:

Compiler catches mistakes before runtime
Autocomplete shows available routes
Associated values carry data type-safely
Refactoring is safe (rename propagates everywhere)

5. Pushed Child Coordinators ⭐

Delegate entire sub-flows to specialised coordinators.

  class ProductCoordinator: Coordinator<ProductRoute> {
      init() {
          super.init(router: Router(initial: .list, factory: factory))

          // Checkout handled by separate coordinator
          let checkoutCoordinator = CheckoutCoordinator()
          addChild(checkoutCoordinator)
      }
  }

When user navigates to a checkout route:

Framework pushes CheckoutCoordinator onto navigation stack
Checkout handles its own navigation independently
Back button automatically returns to parent
Clean separation of concerns

Modular architecture without the complexity.

6. FlowOrchestrator ⭐

Handle major flow transitions (Login ↔ Main App) with automatic lifecycle management.

  class AppCoordinator: FlowOrchestrator<AppRoute> {
      override func handleFlowChange(to route: any Route) -> Bool {
          switch route as? AppRoute {
          case .login:
              transitionToFlow(LoginCoordinator(), root: .login)
              return true
          case .mainApp:
              transitionToFlow(MainTabCoordinator(), root: .mainApp)
              return true
          default:
              return false
          }
      }
  }

What it does:

One line per flow transition
Automatic coordinator deallocation (old flow cleaned up)
Automatic coordinator creation and initialization
Automatic parent-child relationship management
Clean state transitions

Measured result: 50% code reduction for flow transitions in the example app.

Perfect for: Login flows, onboarding sequences, major app state changes (guest → authenticated, trial → paid, etc.)

Getting Started

Installation:

  dependencies: [
      .package(url: "https://github.com/JohnnyPJr/SwiftUIFlow.git", from: "1.0.1")
  ]

Quick Setup:

1. Define enum routes:

 enum AppRoute: Route {
      case home
      case profile
      case settings

      var identifier: String {
          switch self {
          case .home: return "home"
          case .profile: return "profile"
          case .settings: return "settings"
          }
      }
  }

2. Create coordinator:

  class AppCoordinator: Coordinator<AppRoute> {
      init() {
          let factory = AppViewFactory()
          super.init(router: Router(initial: .home, factory: factory))
          factory.coordinator = self
      }

      override func canHandle(_ route: AppRoute) -> Bool {
          return true
      }

      override func navigationType(for route: AppRoute) -> NavigationType {
          switch route {
          case .home, .profile:
              return .push
          case .settings:
              return .modal
          }
      }
  }

3. Create ViewFactory:

  class AppViewFactory: ViewFactory<AppRoute> {
      weak var coordinator: AppCoordinator?

      override func buildView(for route: AppRoute) -> AnyView {
          guard let coordinator else {
              return AnyView(Text("Error: Coordinator not set"))
          }

          switch route {
          case .home:
              return AnyView(HomeView(coordinator: coordinator))
          case .profile:
              return AnyView(ProfileView(coordinator: coordinator))
          case .settings:
              return AnyView(SettingsView(coordinator: coordinator))
          }
      }
  }

4. Bootstrap:

  @main
  struct MyApp: App {
      let coordinator = AppCoordinator()

      var body: some Scene {
          WindowGroup {
              CoordinatorView(coordinator: coordinator)
          }
      }
  }

5. Navigate:

  coordinator.navigate(to: .profile) // Done!

When to Use Coordinator Modals?

Use plain SwiftUI .sheet() for simple modals:

Pickers, selectors, single-screen forms

Use coordinator modals when you need:

Deep linking to the modal
Navigation within the modal (calling .navigate(), not just dismissing)
Custom modal detents (automatic content-sizing with .custom)

Most modals should be plain SwiftUI. Only use coordinator modals when you need the power.

Why SwiftUIFlow

Choose SwiftUIFlow when you need:

✅ Universal navigation — Navigate anywhere from anywhere with one API
✅ Smart automation — Backward detection, modal dismissal, tab switching automatic
✅ Context preservation — Detours for notifications and interruptions
✅ Type safety — Enum routes with compiler protection
✅ Clean architecture — Modular coordinator hierarchy
✅ Less boilerplate — FlowOrchestrator reduces code by 50%
✅ Production-ready — Comprehensive tests, complete docs, battle-tested

Perfect for:

Multi-feature apps with complex navigation
Apps requiring robust deep linking
Teams valuing type safety and testability
Projects needing navigation solved, not reinvented

Not your fit? Simple apps with basic navigation flows are fine with plain SwiftUI NavigationStack.

Imagine This:

You're adding push notifications. Product wants them to deep link anywhere in the app.

Without SwiftUIFlow:

3 hours coordinating state across tabs and modals. 200 lines of custom routing logic. Manual tab switching code. Edge cases you didn't think of. 5 bugs caught in QA. Another 2 slip through.

With SwiftUIFlow:

  func handleNotification(_ route: any Route) {
      coordinator.navigate(to: route) // Done
  }

1 line. 5 minutes. Works first time. Framework handles tabs, modals, state cleanup — everything.

That's what SwiftUIFlow does. Navigation fades into the background. You build features, not infrastructure.

Resources

📖 https://johnnypjr.github.io/SwiftUIFlow/documentation/swiftuiflow/ — 5 comprehensive guides
💻 https://github.com/JohnnyPJr/SwiftUIFlow/tree/main/SwiftUIFlowExample — 21 files showing real patterns
🧪 https://github.com/JohnnyPJr/SwiftUIFlow/tree/main/SwiftUIFlowTests — 25 test files
⭐ https://github.com/JohnnyPJr/SwiftUIFlow

SwiftUIFlow powers production apps. If you've struggled with cross-feature navigation, deep linking, or coordinator boilerplate:
Try SwiftUIFlow today — install via SPM in 2 minutes, navigate from anywhere in 5 minutes.

Coming next:
Part 2: Advanced Patterns — Custom tab bars, navigation paths, and production architectures.

Built by https://github.com/JohnnyPJr — MIT License, open source, community-driven.

DEV Community: Ioannis Platsis