Coordinator · Commitwise

The order details screen has a “Buy again” button. In the first version, the screen itself creates the checkout screen and pushes it. Then product wants “Buy again” from the order list too, then from a push notification, then from a widget. Each place copies the push, with slightly different setup. When checkout gets a new first step (choose an address), four screens have to change, and the one in the notification handler is forgotten.

Screens that navigate to other screens know too much: who comes next, how to build it, and what happens after. A Coordinator takes that knowledge out of the screens. Screens only say what happened (“the user tapped Buy again for order 42”); the coordinator decides where that leads.

New to some of these? Open what you need, or skip ahead.

Basics:What is a navigation stack?

Most apps navigate with a stack of screens: opening a screen pushes it on top, and Back pops it off, revealing the one below. iOS uses UINavigationController or SwiftUI’s NavigationStack; Android Compose uses a NavController with a back stack. The iOS lists and navigation and Android navigation tutorials cover them.

Basics:What is a closure or lambda callback?

A callback is a function you hand to someone so they can call you back later. A screen that takes onOrderTap: (String) -> Unit doesn’t know what happens when an order is tapped; whoever created the screen decides by passing the function.

Part Not started

Screens report, coordinators decide

Think of a museum tour. Each room has a guide who explains the paintings, but the guides don’t decide the route; the tour coordinator does. A guide just says “we’re done here”, and the coordinator says which room is next. The same room can be part of the “highlights” tour and the “full day” tour, because the room doesn’t know which tour it’s in.

In an app:

Screens show things and report what the user did: “tapped order 42”, “finished checkout”, “cancelled”.
The coordinator creates screens, listens to what they report, and decides which screen comes next.

A screen with no navigation code can appear in several flows, and you can test it without building the screens after it.

A Coordinator encapsulates navigation and screen assembly for a flow. Screens (view controllers, composables, views) expose outputs (closures, delegate methods, event lambdas) and never instantiate or present their successors. Coordinators form a tree: an app coordinator starts child coordinators for flows (onboarding, checkout), which report completion with a result and are then released. The pattern originated in UIKit, where UIViewController makes navigation trivially reachable from every screen; in Compose, the equivalent is hoisting navigation out of composables (screens take lambdas; the NavHost graph or a flow-level navigator wires them), and in SwiftUI it’s a router object owning a NavigationStack(path:).

An orders flow where screens only report events

// UIKit: the screen exposes outputs and never pushes anything itself
final class OrderListViewController: UIViewController {
    var onOrderSelected: ((OrderId) -> Void)?
    // in didSelectRowAt: onOrderSelected?(orders[indexPath.row].id)
}

final class OrderDetailViewController: UIViewController {
    var onBuyAgain: ((OrderId) -> Void)?
    init(orderId: OrderId, viewModel: OrderDetailViewModel) { /* … */ super.init(nibName: nil, bundle: nil) }
    required init?(coder: NSCoder) { fatalError() }
}

protocol Coordinator: AnyObject {
    func start()
}

final class OrdersCoordinator: Coordinator {
    private let navigation: UINavigationController
    private let dependencies: AppDependencies
    private var children: [Coordinator] = []

    init(navigation: UINavigationController, dependencies: AppDependencies) {
        self.navigation = navigation
        self.dependencies = dependencies
    }

    func start() {
        let list = OrderListViewController()
        list.onOrderSelected = { [weak self] id in self?.showDetail(id) }
        navigation.pushViewController(list, animated: false)
    }

    func showDetail(_ id: OrderId) {
        let detail = OrderDetailViewController(orderId: id, viewModel: dependencies.orderDetailViewModel(id))
        detail.onBuyAgain = { [weak self] id in self?.startCheckout(reordering: id) }
        navigation.pushViewController(detail, animated: true)
    }

    func startCheckout(reordering id: OrderId) {
        let checkout = CheckoutCoordinator(navigation: navigation, reordering: id, dependencies: dependencies)
        checkout.onFinish = { [weak self, weak checkout] result in
            guard let self, let checkout else { return }
            self.children.removeAll { $0 === checkout }     // release the child flow
            if case .placed(let orderId) = result { self.showDetail(orderId) }
        }
        children.append(checkout)
        checkout.start()
    }
}

// Compose: screens take lambdas; the flow's graph decides what they lead to
@Composable
fun OrderListScreen(viewModel: OrderListViewModel, onOrderSelected: (OrderId) -> Unit) { /* … */ }

@Composable
fun OrderDetailScreen(viewModel: OrderDetailViewModel, onBuyAgain: (OrderId) -> Unit) { /* … */ }

@Serializable data object OrderList
@Serializable data class OrderDetail(val id: String)
@Serializable data class Checkout(val reorderOf: String)

// The coordinator for the orders flow: the only place that navigates
fun NavGraphBuilder.ordersFlow(nav: NavController) {
    composable<OrderList> {
        OrderListScreen(
            viewModel = hiltViewModel(),
            onOrderSelected = { id -> nav.navigate(OrderDetail(id.value)) },
        )
    }
    composable<OrderDetail> {
        OrderDetailScreen(
            viewModel = hiltViewModel(),
            onBuyAgain = { id -> nav.navigate(Checkout(reorderOf = id.value)) },
        )
    }
    checkoutFlow(
        nav = nav,
        onPlaced = { orderId ->
            nav.navigate(OrderDetail(orderId.value)) { popUpTo<OrderList>() }
        },
    )
}

// A framework-neutral coordinator: screens get callbacks, the coordinator owns a Navigator
interface Navigator {
  push(screen: Screen): void;
  pop(): void;
  popTo(predicate: (s: Screen) => boolean): void;
}

class OrdersCoordinator {
  constructor(private readonly nav: Navigator, private readonly deps: AppDependencies) {}

  start() {
    this.nav.push(new OrderListScreen({
      onOrderSelected: (id) => this.showDetail(id),
    }));
  }

  showDetail(id: OrderId) {
    this.nav.push(new OrderDetailScreen(this.deps.orderDetail(id), {
      onBuyAgain: (orderId) => this.startCheckout(orderId),
    }));
  }

  startCheckout(reorderOf: OrderId) {
    new CheckoutCoordinator(this.nav, this.deps, reorderOf, (result) => {
      if (result.kind === "placed") {
        this.nav.popTo((s) => s instanceof OrderListScreen);
        this.showDetail(result.orderId);
      }
    }).start();
  }
}

The screens have no idea what comes after them. OrderDetail just calls onBuyAgain(id).
The coordinator is the only code that creates screens and navigates. Starting checkout from a notification or a widget means calling startCheckout(reordering:), the same function, with the same steps.
Checkout is its own child coordinator. When it finishes, it reports a result (placed or cancelled), and the parent decides what to show next, then lets go of the child.
In Compose, the navigation graph for a flow plays the coordinator’s role: screens receive lambdas, and only the graph calls navigate.

Spot the bugSaving an address goes back two screens

Tap the line with the bug.

final class AddressFormViewController: UIViewController {
    var onSaved: ((Address) -> Void)?

    @objc private func saveTapped() {
        let address = form.address
        onSaved?(address)
        navigationController?.popViewController(animated: true)
    }
}

// In CheckoutCoordinator
form.onSaved = { [weak self] address in
    self?.selectedAddress = address
    self?.navigation.popViewController(animated: true)
}

@Composable
fun AddressFormScreen(
    nav: NavController,
    onSaved: (Address) -> Unit,
) {
    Button(onClick = {
        onSaved(form.address)
        nav.popBackStack()
    }) { Text("Save") }
}

// In the checkout graph
composable<AddressForm> {
    AddressFormScreen(nav, onSaved = { address ->
        checkout.select(address)
        nav.popBackStack()
    })
}

class AddressFormScreen {
  constructor(private nav: Navigator, private callbacks: { onSaved(a: Address): void }) {}

  saveTapped() {
    this.callbacks.onSaved(this.form.address);
    this.nav.pop();
  }
}

// In CheckoutCoordinator
new AddressFormScreen(this.nav, {
  onSaved: (address) => {
    this.selectedAddress = address;
    this.nav.pop();
  },
});

Both the screen and the coordinator pop. Save removes the address form and the screen below it (the checkout summary), so the user lands two screens back, outside checkout, with their order half done. The bug appears only in this flow; in another flow where the coordinator doesn’t pop, the screen’s own pop happens to be right, which is how it sneaks through review.

With coordinators, exactly one place navigates for each event, and it’s the coordinator. The screen reports and does nothing else; it doesn’t even get the navigator:

@objc private func saveTapped() {
    onSaved?(form.address)          // report only; the coordinator pops
}

@Composable
fun AddressFormScreen(onSaved: (Address) -> Unit) {   // no NavController parameter
    Button(onClick = { onSaved(form.address) }) { Text("Save") }
}

saveTapped() {
  this.callbacks.onSaved(this.form.address);   // report only; the coordinator pops
}

Not passing the navigator (NavController, Navigator) into screens at all makes this mistake impossible to write.

Predict the output

The address form is reused in Settings, where saving should show a 'Saved' banner and stay on the form. With the fixed code, what has to change in AddressFormScreen?

Coordinators own navigation and screen assembly per flow; screens expose outputs (closures, delegates, lambdas) and never present successors.
Coordinator tree: parent starts child flows, child reports a result, parent releases it.
Compose: hoist navigation out of composables (screens take lambdas, the graph navigates); SwiftUI: a router owning NavigationStack(path:).
Exactly one place navigates per event: don’t pass the navigator into screens.
Payoff: reusable screens without “which flow am I in” flags, testable flows, one entry point per flow.

Check this part

What does a screen do when the user taps an order, in the coordinator pattern?
The coordinator decides what that leads to.
Why can the same screen appear in several flows?
Each coordinator wires the outputs differently.
In Compose, what usually plays the coordinator role?
Only the graph calls navigate.

A coordinator owns navigation for one flow: it creates screens, gives them callbacks, and decides what comes next when they report events. Screens never create or push other screens, so they can be reused in several flows and tested alone. Only one place navigates for each event.

Part Not started

Big apps have many flows: onboarding, login, checkout, settings. Each one gets its own coordinator, and an app coordinator at the top decides which flow runs: logged out, show login; logged in, show the main tabs.

Two things need care:

Finishing a flow. When checkout is done, its coordinator reports the result and the parent removes it. If the parent keeps it forever, every checkout leaves an old coordinator in memory.
Deep links. A link like /orders/42 should show the order with the order list behind it, so Back works. That’s one coordinator method, showOrder(42), which builds the stack the same way a user tapping would.

The lifecycle is where coordinator code goes wrong. A child coordinator must be removed from its parent when its flow ends by any path: its own completion, cancellation, the user swiping back or tapping Back in the navigation bar (which UIKit performs without asking anyone), or the parent dismissing a modal. In UIKit that means observing UINavigationControllerDelegate.navigationController(_:didShow:animated:) and checking which view controllers were popped, or presentationControllerDidDismiss for sheets. Parent-child references must not form cycles. Deep links and state restoration become coordinator operations that construct the stack from a route, which also centralizes auth gating. With state-driven navigation (SwiftUI NavigationStack(path:), Compose Navigation’s back stack, Navigation 3’s state-owned back stack), the coordinator becomes a router that owns and mutates navigation state, and back gestures update that state for you.

A deep link builds the whole stack

// SwiftUI: the router owns the path; navigation is editing an array
@Observable
final class OrdersRouter {
    enum Route: Hashable { case detail(OrderId), checkout(reorderOf: OrderId) }
    var path: [Route] = []

    func showDetail(_ id: OrderId) { path.append(.detail(id)) }
    func buyAgain(_ id: OrderId) { path.append(.checkout(reorderOf: id)) }
    func checkoutFinished(placed id: OrderId?) {
        path = id.map { [.detail($0)] } ?? Array(path.dropLast())
    }

    // Deep link /orders/42: list at the root, detail on top, so Back works
    func open(orderId: OrderId) { path = [.detail(orderId)] }
}

struct OrdersFlow: View {
    @State private var router = OrdersRouter()
    var body: some View {
        NavigationStack(path: $router.path) {
            OrderListView(onOrderSelected: router.showDetail)
                .navigationDestination(for: OrdersRouter.Route.self) { route in
                    switch route {
                    case .detail(let id): OrderDetailView(id: id, onBuyAgain: router.buyAgain)
                    case .checkout(let id): CheckoutView(reorderOf: id, onFinish: router.checkoutFinished)
                    }
                }
        }
    }
}

// Compose: a deep link handled by the flow, building a back stack with the list underneath
fun NavController.openOrder(id: OrderId) {
    navigate(OrderList) {
        popUpTo(graph.findStartDestination().id)        // clear whatever was there
        launchSingleTop = true
    }
    navigate(OrderDetail(id.value))
}

// Declared deep links do the same automatically: the synthetic back stack
// contains the graph's start destination below the target
composable<OrderDetail>(
    deepLinks = listOf(navDeepLink<OrderDetail>(basePath = "https://shop.example.com/orders")),
) { /* … */ }

class OrdersCoordinator {
  // Deep link /orders/42: same screens, same callbacks as tapping through the app
  openOrder(id: OrderId) {
    this.nav.popTo(() => false);   // back to the root of this navigator
    this.start();                  // order list
    this.showDetail(id);           // detail on top, so Back shows the list
  }
}

Production puzzles

Predict the output

Swift: the parent sets checkout.onFinish = { result in self.children.removeAll { $0 === checkout }; … } with no capture list, and stores checkout in self.children. What happens after a few checkouts?

Predict the output

UIKit: CheckoutCoordinator only calls onFinish from its Cancel and Place order buttons. The user leaves checkout with the interactive back swipe. What state is the app in?

Finishing a UIKit child flow on back swipe

final class CheckoutCoordinator: NSObject, Coordinator, UINavigationControllerDelegate {
    var onFinish: ((CheckoutResult) -> Void)?
    private weak var firstScreen: UIViewController?

    func navigationController(_ nav: UINavigationController, didShow vc: UIViewController, animated: Bool) {
        guard let first = firstScreen,
              let from = nav.transitionCoordinator?.viewController(forKey: .from),
              from === first,
              !nav.viewControllers.contains(first) else { return }
        onFinish?(.cancelled)                    // the user went back past our first screen
    }
}

In a real app, one object owns the navigation controller’s delegate and forwards these events to the active coordinator, since a UINavigationController has only one delegate.

Testing flows

Because screens only report events and the coordinator holds the navigation logic, flows are testable with a fake navigator: call coordinator.showDetail(id), simulate onBuyAgain, and assert the navigator received a push of a checkout screen. With state-driven routers it’s even simpler: assert on router.path.

Exerciseeasy

A login gate

Some deep links need a logged-in user: /orders/42 should open the order, but if the user isn’t logged in, it should show login first and then the order. Where does this logic go, and roughly how does it work?

›

Which object knows whether the user is logged in, and which one knows how to show an order?

SolutionTry it yourself first

In the app coordinator, which decides between the login flow and the main flow:

The deep link is turned into a route, Route.order(42).
If logged in: ask the main coordinator to showOrder(42).
If not: remember the pending route, start the login coordinator, and when it finishes with “logged in”, start the main flow and then showOrder(42). If login is cancelled, drop the pending route.

Screens don’t check login state for navigation, and every deep link gets the same gate for free.

Child coordinators must finish on every exit path: completion, cancel, back swipe, Back button, sheet dismissal (UINavigationControllerDelegate.didShow, presentationControllerDidDismiss).
Break parent ↔ child cycles: [weak self, weak child] in completion closures.
Deep links and restoration: a coordinator method builds the stack from a route; auth gating lives in the app coordinator.
State-driven navigation (SwiftUI path, Compose back stack) turns coordinators into routers and handles back gestures for you.
Flows become testable with a fake navigator or by asserting on router state.

Check this part

What should a parent coordinator do when a child flow finishes?
Otherwise every finished flow stays in memory.
Why can a UIKit back swipe leak a child coordinator?
Observe didShow, or use state-driven navigation.
In SwiftUI with NavigationStack(path:), what is the coordinator?
Navigation is data; the router changes it.

Child coordinators run sub-flows and must be released when they finish, including when the user swipes back. Avoid retain cycles between parent and child. Deep links become a coordinator method that builds the whole stack. In SwiftUI and Compose, navigation state is data, so the coordinator is a router that edits it.

Key takeaways

Screens report what happened; the coordinator decides where to go.
Only one place navigates for each event, so don’t give screens the navigator.
Each flow has its own coordinator, released when the flow ends.
Deep links call the same coordinator methods as taps do.

Outputs on screens, assembly and navigation in coordinators, organized as a tree.
Finish child flows on every exit path and avoid reference cycles.
Centralize deep links, restoration and auth gating in coordinators.
With state-driven navigation, coordinators become routers that own navigation state.

Screens report, coordinators decide

Child flows, deep links and state-based navigation

Production puzzles

Testing flows