Coordinator Pattern — Expert Decisions
Expert decision frameworks for Coordinator pattern choices. Claude knows the pattern — this skill provides judgment calls for when coordinators add value and how to structure hierarchies.
Decision Trees
Do You Need Coordinators?
How many navigation flows does your app have?
├─ 1-2 simple flows
│ └─ Skip coordinators
│ NavigationStack + simple Router is enough
│
├─ 3-5 distinct flows
│ └─ Consider coordinators IF:
│ • Flows have complex branching
│ • Deep linking is required
│ • Flows need to share navigation logic
│
└─ 6+ flows or multi-team development
└─ Coordinators recommended
• Clear ownership boundaries
• Parallel development possible
• Testable navigation logic
The trap: Adding coordinators to simple apps. If your app is 5 screens with linear flow, coordinators add complexity without benefit.
Coordinator Hierarchy Design
Does this flow need to manage sub-flows?
├─ NO (leaf coordinator)
│ └─ Simple coordinator
│ Owns NavigationPath, creates views
│
└─ YES (has sub-flows)
└─ Parent coordinator
Manages childCoordinators array
Delegates to child for sub-flows
SwiftUI vs UIKit Coordinator
Which UI framework?
├─ SwiftUI
│ └─ Coordinator as ObservableObject
│ • Owns NavigationPath
│ • @ViewBuilder for destinations
│ • Pass via EnvironmentObject or explicit injection
│
└─ UIKit
└─ Coordinator owns UINavigationController
• Creates and pushes ViewControllers
• Uses delegation for flow completion
• Manages childCoordinators manually
Flow Completion Strategy
How does a flow end?
├─ Success (user completed task)
│ └─ Delegate method with result
│ coordinator.didCompleteLogin(user: user)
│
├─ Cancellation (user backed out)
│ └─ Delegate method without result
│ coordinator.didCancelLogin()
│
└─ Automatic (flow naturally ends)
└─ Parent removes child automatically
No explicit completion needed
NEVER Do
Child Coordinator Lifecycle
NEVER forget to remove child coordinators:
// ❌ Memory leak — child coordinator retained forever
final class ParentCoordinator {
var childCoordinators: [Coordinator] = []
func startLoginFlow() {
let loginCoordinator = LoginCoordinator()
childCoordinators.append(loginCoordinator)
loginCoordinator.start()
// Never removed! Leaks.
}
}
// ✅ Remove child on flow completion
final class ParentCoordinator: LoginCoordinatorDelegate {
var childCoordinators: [Coordinator] = []
func startLoginFlow() {
let loginCoordinator = LoginCoordinator()
loginCoordinator.delegate = self
childCoordinators.append(loginCoordinator)
loginCoordinator.start()
}
func loginCoordinatorDidFinish(_ coordinator: LoginCoordinator) {
childCoordinators.removeAll { $0 === coordinator }
}
}
NEVER use strong parent references:
// ❌ Retain cycle — coordinator never deallocates
final class ChildCoordinator {
var parent: ParentCoordinator // Strong reference!
}
// ✅ Weak parent or delegate
final class ChildCoordinator {
weak var delegate: ChildCoordinatorDelegate?
// OR
weak var parent: ParentCoordinator?
}
Coordinator Responsibilities
NEVER put business logic in coordinators:
// ❌ Coordinator doing business logic
final class CheckoutCoordinator {
func completeOrder() async {
// Business logic leaked into coordinator!
let total = cart.items.reduce(0) { $0 + $1.price }
let tax = total * 0.08
try await paymentService.charge(total + tax)
}
}
// ✅ Coordinator orchestrates, ViewModel/UseCase handles logic
final class CheckoutCoordinator {
func showCheckout() {
let viewModel = CheckoutViewModel(
cartService: container.cartService,
paymentService: container.paymentService
)
// ViewModel handles business logic
}
}
NEVER let views know about coordinator hierarchy:
// ❌ View knows about parent coordinator
struct LoginView: View {
let coordinator: LoginCoordinator
var body: some View {
Button("Done") {
coordinator.parent?.childDidFinish(coordinator) // Wrong!
}
}
}
// ✅ View only knows its immediate coordinator
struct LoginView: View {
let coordinator: LoginCoordinator
var body: some View {
Button("Done") {
coordinator.completeLogin() // Coordinator handles delegation
}
}
}
SwiftUI-Specific
NEVER create coordinators as @StateObject in child views:
// ❌ New coordinator created on every parent rebuild
struct ParentView: View {
var body: some View {
ChildView() // Child creates its own coordinator
}
}
struct ChildView: View {
@StateObject var coordinator = ChildCoordinator() // Wrong!
}
// ✅ Parent creates and owns coordinator
struct ParentView: View {
@StateObject var childCoordinator = ChildCoordinator()
var body: some View {
ChildView(coordinator: childCoordinator)
}
}
NEVER use NavigationLink directly when using coordinators:
// ❌ Bypasses coordinator — navigation untracked
struct UserListView: View {
var body: some View {
NavigationLink("User") {
UserDetailView() // Coordinator doesn't know about this!
}
}
}
// ✅ Delegate navigation to coordinator
struct UserListView: View {
@ObservedObject var coordinator: UsersCoordinator
var body: some View {
Button("User") {
coordinator.showUserDetail(userId: "123")
}
}
}
Essential Patterns
SwiftUI Coordinator Protocol
@MainActor
protocol Coordinator: ObservableObject {
associatedtype Route: Hashable
var path: NavigationPath { get set }
func start() -> AnyView
func navigate(to route: Route)
func pop()
func popToRoot()
}
extension Coordinator {
func pop() {
guard !path.isEmpty else { return }
path.removeLast()
}
func popToRoot() {
path = NavigationPath()
}
}
Parent-Child Coordinator
@MainActor
protocol ParentCoordinatorProtocol: AnyObject {
var childCoordinators: [any Coordinator] { get set }
func addChild(_ coordinator: any Coordinator)
func removeChild(_ coordinator: any Coordinator)
}
extension ParentCoordinatorProtocol {
func addChild(_ coordinator: any Coordinator) {
childCoordinators.append(coordinator)
}
func removeChild(_ coordinator: any Coordinator) {
childCoordinators.removeAll { $0 === coordinator as AnyObject }
}
}
// Tab coordinator managing child coordinators
@MainActor
final class TabCoordinator: ParentCoordinatorProtocol, ObservableObject {
var childCoordinators: [any Coordinator] = []
lazy var homeCoordinator: HomeCoordinator = {
let coordinator = HomeCoordinator()
coordinator.parent = self
addChild(coordinator)
return coordinator
}()
lazy var profileCoordinator: ProfileCoordinator = {
let coordinator = ProfileCoordinator()
coordinator.parent = self
addChild(coordinator)
return coordinator
}()
}
Flow Completion with Result
protocol LoginCoordinatorDelegate: AnyObject {
func loginCoordinator(_ coordinator: LoginCoordinator, didFinishWith result: LoginResult)
}
enum LoginResult {
case success(User)
case cancelled
}
@MainActor
final class LoginCoordinator: ObservableObject {
weak var delegate: LoginCoordinatorDelegate?
@Published var path = NavigationPath()
enum Route: Hashable {
case credentials
case forgotPassword
case twoFactor(email: String)
}
func completeLogin(user: User) {
delegate?.loginCoordinator(self, didFinishWith: .success(user))
}
func cancel() {
delegate?.loginCoordinator(self, didFinishWith: .cancelled)
}
}
Deep Link Integration
@MainActor
final class AppCoordinator: ObservableObject, ParentCoordinatorProtocol {
var childCoordinators: [any Coordinator] = []
@Published var path = NavigationPath()
func handle(deepLink: DeepLink) {
// Reset to known state
popToRoot()
childCoordinators.forEach { removeChild($0) }
// Navigate to deep link destination
switch deepLink {
case .user(let id):
navigate(to: .userList)
navigate(to: .userDetail(userId: id))
case .checkout:
let checkoutCoordinator = CheckoutCoordinator()
checkoutCoordinator.delegate = self
addChild(checkoutCoordinator)
// Present checkout flow
case .settings(let section):
navigate(to: .settings)
if let section = section {
navigate(to: .settingsSection(section))
}
}
}
}
Quick Reference
Coordinator Checklist
- [ ] Coordinator owns NavigationPath (SwiftUI) or UINavigationController (UIKit)
- [ ] Parent-child references are weak
- [ ] Child coordinators removed on flow completion
- [ ] Views don't know about coordinator hierarchy
- [ ] Business logic stays in ViewModels/UseCases
- [ ] Deep links handled at appropriate coordinator level
When to Use Coordinators
| Scenario | Use Coordinator? | |----------|------------------| | Simple 3-5 screen app | No — simple Router | | Multiple independent flows | Yes | | Deep linking required | Likely yes | | Multi-step wizard flows | Yes | | Cross-tab navigation | Yes | | A/B testing navigation | Yes | | Team-based feature ownership | Yes |
Red Flags
| Smell | Problem | Fix | |-------|---------|-----| | childCoordinators grows forever | Memory leak | Remove on completion | | Strong parent reference | Retain cycle | Use weak or delegate | | Business logic in coordinator | Wrong layer | Move to ViewModel/UseCase | | View creates NavigationLink | Bypasses coordinator | Delegate to coordinator | | @StateObject coordinator in child | Recreated on rebuild | Parent owns coordinator | | Coordinator creates its own views | Can't inject dependencies | Use ViewFactory |
Coordinator vs Router
| Aspect | Coordinator | Router | |--------|-------------|--------| | Complexity | Higher | Lower | | Hierarchy support | Yes (parent-child) | No | | Flow isolation | Strong | Weak | | Testing | Excellent | Good | | Learning curve | Steep | Gentle | | Best for | Large apps, teams | Small-medium apps |