Stack-based Navigation

Learn about stack-based navigation with collections, including domain modeling, feature integration, testing, UIKit support, and more

Overview

Stack-based navigation models navigation using collections of state. This allows deep-linking by constructing flat collections of data and supports complex, recursive navigation paths.

Key tools:

• StackState collection type
• StackAction type
• .forEach(_:action:) reducer operator
• Custom NavigationStack initializer

Basics

Integrating features into a navigation stack involves two main steps: integrating domains and constructing the NavigationStack view.

Step 1: Define Path Reducer

Create a reducer holding all features that can be pushed onto the stack:

@Reducer
struct RootFeature {
  // ...

  @Reducer
  enum Path {
    case addItem(AddFeature)
    case detailItem(DetailFeature)
    case editItem(EditFeature)
  }
}

The Path reducer is identical to the Destination reducer used in tree-based navigation with enums.

Step 2: Add StackState and StackAction

Hold navigation stack state and actions in the root feature:

@Reducer
struct RootFeature {
  @ObservableState
  struct State {
    var path = StackState<Path.State>()
    // ...
  }
  enum Action {
    case path(StackActionOf<Path>)
    // ...
  }
}

StackActionOf is a typealias that simplifies the syntax for StackAction, which is generic over both state and action.

Step 3: Integrate with .forEach

Use .forEach to integrate path features with the parent:

@Reducer
struct RootFeature {
  // ...

  var body: some ReducerOf<Self> {
    Reduce { state, action in 
      // Core logic for root feature
    }
    .forEach(\.path, action: \.path)
  }
}

Step 4: Build NavigationStack View

Use the custom NavigationStack initializer that takes a store binding:

struct RootView: View {
  @Bindable var store: StoreOf<RootFeature>

  var body: some View {
    NavigationStack(
      path: $store.scope(state: \.path, action: \.path)
    ) {
      // Root view of the navigation stack
    } destination: { store in
      // A view for each case of the Path.State enum
    }
  }
}

Step 5: Handle Each Path Case

Use store.case to destructure each case and return the appropriate view:

NavigationStack(
  path: $store.scope(state: \.path, action: \.path)
) {
  Form {
    // Root view content
  }
} destination: { store in
  switch store.case {
  case .addItem(let store):
    AddView(store: store)
  case .detailItem(let store):
    DetailView(store: store)
  case .editItem(let store):
    EditView(store: store)
  }
}

Switching on store.case gives compile-time guarantees that you’ve handled all path cases.

Pushing Features onto the Stack

There are two primary ways to push features onto the stack:

1. Using NavigationLink (Simple)

Use the custom NavigationLink initializer with full state:

Form {
  NavigationLink(
    state: RootFeature.Path.State.detail(DetailFeature.State())
  ) {
    Text("Detail")
  }
}

When tapped, a StackAction.push(id:state:) action is sent, appending to the stack.

Drawback: This approach requires the view to access Path.State, meaning it must build all features in the path. This hurts modularity.

2. Using Button + Action (Modular)

Send an action from the child feature:

Form {
  Button("Detail") {
    store.send(.detailButtonTapped)
  }
}

The root feature listens and appends to the path:

case .path(.element(id: _, action: .list(.detailButtonTapped))):
  state.path.append(.detail(DetailFeature.State()))
  return .none

This approach maintains modularity since the child feature doesn’t need to know about Path.State.

Integration

Parent features have instant access to everything in the stack. Detect child actions by destructuring:

case let .path(.element(id: id, action: .editItem(.saveButtonTapped))):
  guard let editItemState = state.path[id: id]?.editItem
  else { return .none }

  state.path.pop(from: id)
  return .run { _ in
    await self.database.save(editItemState.item)
  }

When destructuring StackAction.element(id:action:), you get both:

• The action that happened
• The ID of the element in the stack

StackState automatically manages IDs for every feature.

Dismissal

Dismiss features by mutating StackState:

case .closeButtonTapped:
  state.path.popLast()
  return .none

Available methods:

• popLast() - Remove last element
• pop(from:) - Remove from specific ID
• And more collection methods

Self-Dismissal from Child

Use @Dependency(\.dismiss) to allow children to dismiss themselves:

@Reducer
struct Feature {
  @ObservableState
  struct State { /* ... */ }
  enum Action { 
    case closeButtonTapped
    // ...
  }
  @Dependency(\.dismiss) var dismiss
  
  var body: some Reducer<State, Action> {
    Reduce { state, action in
      switch action {
      case .closeButtonTapped:
        return .run { _ in await self.dismiss() }
      // ...
      }
    }
  }
}

When dismiss() is called, a StackAction.popFrom(id:) action is sent to remove the feature from the stack.

Important: Never send actions after calling dismiss():

return .run { send in 
  await self.dismiss()
  await send(.tick)  // ⚠️ Don't do this!
}

The feature’s state is no longer in the stack, causing runtime warnings and test failures.

SwiftUI’s @Environment(\.dismiss) and TCA’s @Dependency(\.dismiss) are different types:

• SwiftUI’s: Use in views only
• TCA’s: Use in reducers only

Testing

Using TCA’s tools makes testing navigation stacks straightforward. Non-exhaustive testing is especially useful.

Example: Testing Dismissal

Counter feature that dismisses when count ≥ 5:

@Reducer
struct CounterFeature {
  @ObservableState
  struct State: Equatable {
    var count = 0
  }
  enum Action {
    case decrementButtonTapped
    case incrementButtonTapped
  }

  @Dependency(\.dismiss) var dismiss

  var body: some Reducer<State, Action> {
    Reduce { state, action in
      switch action {
      case .decrementButtonTapped:
        state.count -= 1
        return .none

      case .incrementButtonTapped:
        state.count += 1
        return state.count >= 5
          ? .run { _ in await self.dismiss() }
          : .none
      }
    }
  }
}

Parent feature:

@Reducer
struct Feature {
  @ObservableState
  struct State: Equatable {
    var path = StackState<Path.State>()
  }
  enum Action {
    case path(StackActionOf<Path>)
  }

  @Reducer  
  struct Path {
    enum State: Equatable { case counter(CounterFeature.State) }
    enum Action { case counter(CounterFeature.Action) }
    var body: some ReducerOf<Self> {
      Scope(state: \.counter, action: \.counter) { CounterFeature() }
    }
  }

  var body: some ReducerOf<Self> {
    Reduce { state, action in
      // Logic and behavior for core feature.
    }
    .forEach(\.path, action: \.path) { Path() }
  }
}

Test with IDs

Construct a test store with a counter already on the stack:

@Test
func dismissal() {
  let store = TestStore(
    initialState: Feature.State(
      path: StackState([
        CounterFeature.State(count: 3)
      ])
    )
  ) {
    CounterFeature()
  }
}

StackState automatically manages IDs. In tests, IDs are integers starting at 0 and incrementing for each feature pushed.

Send actions using ID 0:

await store.send(\.path[id: 0].counter.incrementButtonTapped) {
  // ...
}

Two Ways to Assert State Changes

Option 1: Using XCTModify

await store.send(\.path[id: 0].counter.incrementButtonTapped) {
  XCTModify(&$0.path[id: 0], case: \.counter) {
    $0.count = 4
  }
}

XCTModify takes an inout enum, extracts the case payload, lets you mutate it, and embeds it back.

Option 2: Using Double Subscript

await store.send(\.path[id: 0].counter.incrementButtonTapped) {
  $0.path[id: 0, case: \.counter]?.count = 4
}

Simultaneously subscripts into an ID and a case of the enum.

Use XCTModify for many mutations, double subscript for simple ones.

Complete Test

@Test
func dismissal() {
  let store = TestStore(
    initialState: Feature.State(
      path: StackState([
        CounterFeature.State(count: 3)
      ])
    )
  ) {
    CounterFeature()
  }

  await store.send(\.path[id: 0].counter.incrementButtonTapped) {
    XCTModify(&$0.path[id: 0], case: \.counter) {
      $0.count = 4
    }
  }
  
  await store.send(\.path[id: 0].counter.incrementButtonTapped) {
    XCTModify(&$0.path[id: 0], case: \.counter) {
      $0.count = 5
    }
  }
  
  await store.receive(\.path.popFrom) {
    $0.path[id: 0] = nil
  }
}

Receiving Child Actions

To assert a specific child action is received, use subscript on the case key path:

await store.receive(\.path[id: 0].counter.response) {
  // ...
}

Non-Exhaustive Test

Turn off exhaustivity for high-level assertions:

@Test
func dismissal() {
  let store = TestStore(
    initialState: Feature.State(
      path: StackState([
        CounterFeature.State(count: 3)
      ])
    )
  ) {
    CounterFeature()
  }
  store.exhaustivity = .off

  await store.send(\.path[id: 0].counter.incrementButtonTapped)
  await store.send(\.path[id: 0].counter.incrementButtonTapped)
  await store.receive(\.path.popFrom)
}

Non-exhaustive tests are more concise and resilient to changes you don’t care about.

StackState vs NavigationPath

SwiftUI provides NavigationPath, so why use StackState?

NavigationPath

Pros:

• Type-erased list of any Hashable data
• Maximal feature decoupling

Cons:

• Limited API: only append, removeLast, and count
• Cannot insert/remove from middle
• Cannot iterate over elements
• Hard to analyze stack contents

var path = NavigationPath()
path.append(1)
path.append("Hello")
path.append(false)
path.count  // 3

for element in path {  // 🛑 Not allowed
}

StackState

Pros:

• Conforms to Collection, RandomAccessCollection, RangeReplaceableCollection
• Access to many collection manipulation methods
• Can iterate, insert, remove anywhere
• Automatic stable identifier management
• Data doesn’t need to be Hashable

Cons:

• Fully statically typed (less flexible than type erasure)

var stack = StackState<Path.State>()
stack.append(.detail(...))
stack.append(.edit(...))

// Iterate
for element in stack {
  // Process each feature
}

// Insert/remove anywhere
stack.insert(.add(...), at: 1)
stack.remove(at: 0)

StackState balances runtime flexibility with static, compile-time guarantees—perfect for TCA navigation.

UIKit

TCA provides NavigationStackController for state-driven UINavigationController:

class AppController: NavigationStackController {
  private var store: StoreOf<AppFeature>!

  convenience init(store: StoreOf<AppFeature>) {
    @UIBindable var store = store

    self.init(path: $store.scope(state: \.path, action: \.path)) {
      RootViewController(store: store)
    } destination: { store in 
      switch store.case {
      case .addItem(let store):
        AddViewController(store: store)
      case .detailItem(let store):
        DetailViewController(store: store)
      case .editItem(let store):
        EditViewController(store: store)
      }
    }

    self.store = store
  }
}

Model your domains using StackState as described above, then use NavigationStackController to implement UIKit navigation.

Related

Navigation Overview

Learn about navigation concepts and patterns

Tree-based Navigation

Learn about navigation with optionals and enums