Advanced Navigation Support for SwiftUI.
Navigator provides SwiftUI with a simple yet powerful navigation layer based on NavigationStack.
It supports...
- Simple and easy navigation linking and presentation of views.
- Coordination patterns with well-defined separation of concerns.
- External deep linking and internal application navigation via navigation send.
- Easily returning to a specific spot in the navigation tree via navigation checkpoints.
- Returning callback values via navigation checkpoints.
- Both Declarative and Imperative navigation and control.
- Navigation state restoration.
- Event logging and debugging.
Navigator is written entirely in Swift and SwiftUI, and supports iOS 16 and above.
Destinations (or routes) are typically just public lists of enumerated values, one for each view desired.
public enum HomeDestinations {
case page2
case page3
case pageN(Int)
}SwiftUI requires navigation destination values to be Hashable, and so do we.
Next, we extend each destination with a variable that returns the correct view for each case.
extension HomeDestinations: NavigationDestination {
public var view: some View {
switch self {
case .page2:
HomePage2View()
case .page3:
HomePage3View()
case .pageN(let value):
HomePageNView(number: value)
}
}
}Note how associated values can be used to pass parameters to views as needed.
To build views that have external dependencies or that require access to environmental values, see Advanced Destinations below.
Like traditional NavigationStack destination types, NavigationDestination types need to be registered with the enclosing
navigation stack in order for navigate(to:) presentations and standard NavigationLink(value:label:) transitions
to work correctly.
But since each NavigationDestination already defines the views to be provided, registering destination types can be done
using a simple one-line view modifier.
ManagedNavigationStack {
HomeView()
.navigationDestination(HomeDestinations.self)
}This also makes using the same destination type with more than one navigation stack a lot easier.
With that out of the way, Navigation Destinations can be dispatched using a standard SwiftUI NavigationLink(value:label:) view.
NavigationLink(value: HomeDestinations.page3) {
Text("Link to Home Page 3!")
}Or they can be dispatched declaratively using modifiers.
// Sample using optional destination
@State var page: SettingsDestinations?
...
Button("Modifier Navigate to Page 3!") {
page = .page3
}
.navigate(to: $page)
// Sample using trigger value
@State var triggerPage3: Bool = false
...
Button("Modifier Trigger Page 3!") {
triggerPage3.toggle()
}
.navigate(trigger: $triggerPage3, destination: SettingsDestinations.page3)Or imperatively by asking a Navigator to perform the desired action.
@Environment(\.navigator) var navigator: Navigator
...
Button("Button Push Home Page 55") {
navigator.push(HomeDestinations.pageN(55))
}
Button("Button Navigate To Home Page 55") {
navigator.navigate(to: HomeDestinations.pageN(55))
}In case you're wondering, calling push pushes the associate view onto the current NavigationStack, while Navigate(to:) will push
the view or present the view, based on the NavigationMethod specified (coming up next).
NavigationDestination can be extended to provide a distinct NavigationMethod for each enumerated type.
extension HomeDestinations: NavigationDestination {
public var method: NavigationMethod {
switch self {
case .page3:
.sheet
default:
.push
}
}
}In this case, should navigator.navigate(to: HomeDestinations.page3) be called, Navigator will automatically present that view in a
sheet. All other views will be pushed onto the navigation stack.
The current navigation methods are: .push (default), .sheet, .cover, and .send.
Predefined methods can be overridden using Navigator's navigate(to:method:) function.
Button("Present Home Page 55 Via Sheet") {
navigator.navigate(to: HomeDestinations.pageN(55), method: .sheet)
}Note that destinations dispatched via NavigationLink will always push onto the NavigationStack. That's just how SwiftUI works.
While one can programmatically pop and dismiss their way out of a screen, that approach is problematic and fragile. One could pass bindings down the tree, but that can be equally problematic at worst, and cumbersome at best.
Fortunately, Navigator supports checkpoints; named points in the navigation stack to which one can easily return.
Checkpoints are easy to define and use. Let's create one called "home" and then use it.
extension NavigationCheckpoint {
public static let home: NavigationCheckpoint = "home"
}
struct RootHomeView: View {
var body: some View {
ManagedNavigationStack(scene: "home") {
HomeContentView(title: "Home Navigation")
.navigationCheckpoint(.home)
.navigationDestination(HomeDestinations.self)
}
}
}Once defined, they're easy to use.
Button("Return To Checkpoint Home") {
navigator.returnToCheckpoint(.home)
}
.disabled(!navigator.canReturnToCheckpoint(.home))When fired, checkpoints will dismiss any presented screens and pop any pushed views to return exactly where desired.
Checkpoints can also be used to return values to a caller.
// Define a checkpoint with a value handler.
.navigationCheckpoint(.settings) { (result: Int?) in
returnValue = result
}
// Return, passing a value.
Button("Return to Settings Checkpoint Passing Value 5") {
navigator.returnToCheckpoint(.settings, value: 5)
}Checkpoints are a powerful tool. Use them.
Navigator supports external deep linking and internal application navigation via navigation send.
This comes in handy when navigation means needing to change non-NavigationStack-based values like the selected tab, or perhaps an account number used to trigger the detail view in a NavigationSplitView.
Consider the following fairly standard RootTabView.
struct RootTabView : View {
@SceneStorage("selectedTab") var selectedTab: RootTabs = .home
var body: some View {
TabView(selection: $selectedTab) {
RootHomeView()
.tabItem { Label("Home", systemImage: "house") }
.tag(RootTabs.home)
RootSettingsView()
.tabItem { Label("Settings", systemImage: "gear") }
.tag(RootTabs.settings)
}
.onNavigationReceive { (tab: RootTabs, navigator) in
navigator.dismissAll()
selectedTab = tab
return .auto
}
}
}Sharp eyes may have spotted the onNavigationReceive modifier, which--much like navigationDestination(MyType.self)--is listening for Navigator to broadcast a value of type RootTabs.
When received, Navigator will dismiss any presented screens, set the selected tab, and then return normally.
Values are broadcast using navigationSend() or navigationSend(values:), as shown below.
Button("Send Tab Home, Page 2") {
navigator.send(values: [
RootTabs.home,
HomeDestinations.page2
])
}The RootTabs receiver switches to the selected tab, and then a similar HomeDestinations receiver sends the user to page 2.
.onNavigationReceive { (destination: HomeDestinations, navigator) in
navigator.navigate(to: destination)
return .auto
}This mechanism makes deep linking and internal navigation support simple and easy.
What if we can't construct a specific view without external dependencies or without accessing the environment?
Simple. Just delegate the view building to a standard SwiftUI view!
extension HomeDestinations: NavigationDestination {
public var view: some View {
HomeDestinationsView(destination: self)
}
}
private struct HomeDestinationsView: View {
let destination: HomeDestinations
@Environment(\.coreDependencies) var resolver
var body: some View {
switch self {
case .home:
HomePageView(viewModel: HomePageViewModel(dependencies: resolver))
case .page2:
HomePage2View(viewModel: HomePage2ViewModel(dependencies: resolver))
case .page3:
HomePage3View(viewModel: HomePage3ViewModel(dependencies: resolver))
case .pageN(let value):
HomePageNView(viewModel: HomePageNViewModel(dependencies: resolver), number: value)
}
}
}In the above code, we obtain a coreDependencies resolver from the environment, and then use it to construct our views
and view models.
Note this technique can be used to construct and use fully functional views elsewhere in your view code. Consider.
struct RootHomeView: View {
var body: some View {
ManagedNavigationStack(scene: "home") {
HomeDestinations.home()
.navigationDestination(HomeDestinations.self)
}
}
}Calling the destination as a function obtains a fully resolved HomePageView and view model from HomeDestinationsView,
complete and ready to go.
See the 'DemoDependency.swift' file in the NavigatorDemo project for a possible dependency injection mechanism.
A single README file barely scratches the surface. Fortunately, Navigator is throughly documented.
Current DocC documentation can be found in the project.
Navigator supports the Swift Package Manager.
Or download the source files and add the Navigator folder to your project.
Note that the current version of Navigator requires Swift 5.10 minimum and that the minimum version of iOS currently supported with this release is iOS 16.
Discussion and comments on Navigator can be found in Discussions. Go there if you have something to say or if you want to stay up to date.
Navigator is available under the MIT license. See the LICENSE file for more info.
If you want to support my work on Navigator, Factory and my other open source projects, consider a GitHub Sponsorship! Many levels exist for increased support and even for mentorship and company training.
Or you can just buy me a cup of coffee!
Navigator is designed, implemented, documented, and maintained by Michael Long, a Lead iOS Software Engineer and a Top 1,000 Technology Writer on Medium.
- LinkedIn: @hmlong
- Medium: @michaellong
- BlueSky: @hmlongco
Michael was also one of Google's Open Source Peer Reward winners in 2021 for his work on Resolver.