A lightweight library which makes SwiftUI navigation super easy to use
? NavigationKit
NavigationKit is a lightweight library which makes SwiftUI
navigation super easy to use.
? Installation
? Swift Package Manager
Using Swift Package Manager, add it as a Swift Package in Xcode 11.0 or later, select File > Swift Packages > Add Package Dependency...
and add the repository URL:
https://github.com/rebeloper/NavigationKit.git
✊ Manual Installation
Download and include the NavigationKit
folder and files in your codebase.
? Requirements
- iOS 14+
- Swift 5.3+
? Video Tutorial
SwiftUI Navigation - How to Navigate in SwiftUI Apps on YouTube
This tutorial was made for v.0.1.0.
I have improved and made NavigationKit
even easier to use since this video. Read on to see how to use the newest version.
? Import
Import NavigationKit
into your View
import NavigationKit
? Features
Here's the list of the awesome features NavigationKit
has:
- [X] default / custom transitions
- [X] push
- [X] push to view with id
- [X] pop
- [X] pop to view with id
- [X] pop to root
- [X] present (as modal / full screen)
- [X] may disable swipe down to dismiss on modal
- [X] dismiss
- [X] dismiss to root
- [X] combine
push
withpresent
(good for showing Login / Onboarding / Tutorial) - [X] built in Navigation Bars as view-modifiers (or build and use your own dream nav bar)
- [X] works perfectly with
TabView
In SwiftUI navigtion is handeled by the NavigationView
and NavigationLink
. At the moment these views have some limitations:
- transition animations cannot be turned off or customised;
- we can't navigate back either to root (i.e. the first app view), or to a specific view;
- we can't push programmatically without using a
View
; - customizing the
NavigationBar
is limited or it has to be done viaUINavigationBar.appearance()
(usingUIKit
?); presenting
a view modally is done with the.sheet
and.fullScreenCover
view-modifiers adding confusion to theNavigationLink
'spush
like pattern;
NavigationKitView
is a view that mimics all the behaviours belonging to the standard NavigationView
, but it adds the features listed here above. You have to wrap your view hierarchy inside a NavigationKitView
:
import NavigationKit
struct RootView: View {
var body: some View {
NavigationKitView {
Tab_0_0_View()
}
}
}
You can even customise transitions and animations in some different ways. The NavigationKitView
will apply them to the hierarchy:
- you could decide to go for no transition at all by creating the navigation stack this way
NavigationStackView(transitionType: .none)
; - you could create the navigation stack with a custom transition:
import NavigationKit
struct RootView: View {
var body: some View {
NavigationKitView(transitionType: .custom(.scale)) {
Tab_0_0_View()
}
}
}
NavigationKitView
has a default easing for transitions. The easing can be customised during the initialisation
struct RootView: View {
var body: some View {
NavigationKitView(transitionType: .custom(.scale), easing: .spring(response: 0.5, dampingFraction: 0.25, blendDuration: 0.5)) {
Tab_0_0_View()
}
}
}
Important: The above is the recommended way to customise the easing function for your transitions. Please, note that you could even specify the easing this other way:
NavigationKitView(transitionType: .custom(AnyTransition.scale.animation(.spring(response: 0.5, dampingFraction: 0.25, blendDuration: 0.5))))
Attaching the easing directly to the transition? Don't do this. SwiftUI has still some problems with implicit animations attached to transitions, so it may not work. For example, implicit animations attached to a .slide transition won't work.
⬅️ Push
In order to navigate forward you have to push
with an optional delay
:
import NavigationKit
struct Tab_0_0_View: View {
@EnvironmentObject private var navigation: Navigation
var body: some View {
VStack {
Button {
navigation.push(Tab_0_1_View(), delay: 1.5)
} label: {
Text("Next")
}
Spacer()
}
}
}
Make sure you are using a view model in order for values to persist between push/pop operations. SwiftUI resets all the properties of a view marked with @State
every time the view is removed from a view hierarchy. For the NavigationKitView
this is a problem because when I come back to a previous view (with a pop operation) I want all my view controls to be as I left them before (for example I want my TextField
s to contain the text I previously typed in). It seems that the solution to this problem is using the .id
modifier specifying an id for the views I don't want SwiftUI to reset. According to the Apple documentation the .id
modifier:
Generates a uniquely identified view that can be inserted or removed.
but again, it seems that this API is currently not working as expected (take a look at this interesting post: https://swiftui-lab.com/swiftui-id/). In order to workaround this problem, then, you have to use @ObservableObject
when you need to make some state persist between push/pop operations.
import NavigationKit
struct Tab_0_0_View: View {
@EnvironmentObject private var navigation: Navigation
@ObservedObject private var viewModel = Tab_0_0_ViewModel()
var body: some View {
VStack {
TextField("Type something...", text: $viewModel.text)
.textFieldStyle(RoundedBorderTextFieldStyle())
Button {
self.viewModel.fetchData { (result) in
switch result {
case .success(let finished):
if finished {
navigation.push(Tab_0_2_View())
} else {
print("Something went wrong")
}
case .failure(let err):
print(err.localizedDescription)
}
}
} label: {
Text("Push after model operation")
}
Spacer()
}
}
}
? Specifying an ID
It's not mandatory, but if you want to come back to a specific view at some point later you need to specify an ID for that view:
Button {
navigation.push(Tab_0_1_View(), withId: "Tab_0_1_View")
} label: {
Text("Next")
}
You will be able to pop
to this view using the id
. Read on. ?
➡️ Pop
Pop operation works as the push operation, with an optional delay
:
Button {
navigation.pop(delay: 1.5)
} label: {
Label("Back", systemImage: "chevron.backward")
}
which pops to the previous view. You can even specify a destination for your pop operation:
Button {
navigation.pop(to: .view(withId: "Tab_0_1_View"))
} label: {
Text("Pop to Tab_0_1_View")
}
We can also pop to root like so:
Button {
navigation.pop(to: .root)
} label: {
Text("Pop to Root")
}
? NavigationBar
NavigationKit
replaces NavigationView
altogether. In order to see a navigation bar you can create your own or use the built in view modifiers. You must add them as a modifier of a VStack
which contains a Spacer
to push its content up.
Inline navigation bar
VStack {
...
Spacer()
}
.inlineNavigationBar(titleView:
Text("Tab_0_1_View").bold(),
leadingView:
Button {
navigation.pop()
} label: {
Label("Back", systemImage: "chevron.backward")
},
trailingView:
Button {
navigation.push(Tab_0_2_View())
} label: {
Text("Next")
},
backgroundView:
Color(.secondarySystemBackground).edgesIgnoringSafeArea(.top)
)
Large navigation bar
VStack {
...
Spacer()
}
.largeNavigationBar(titleView:
Text("Tab_0_0_View").bold().lineLimit(1),
leadingView:
EmptyView(),
trailingView:
Button {
navigation.push(Tab_0_1_View(), withId: "Tab_0_1_View")
} label: {
Text("Next")
},
backgroundView:
Color(.secondarySystemBackground).edgesIgnoringSafeArea(.top)
)
Custom navigation bar
var body: some View {
VStack {
...
Spacer()
}.customNavigationBar(titleView:
HStack {
Text("TODAY").font(.title).fontWeight(.light)
Spacer()
Text(todayString().uppercased()).font(.title).fontWeight(.light)
},
backgroundView:
Color(.secondarySystemBackground).edgesIgnoringSafeArea(.top)
)
}
func todayString() -> String {
let formatter = DateFormatter()
formatter.dateFormat = "EEE MM/dd"
return formatter.string(from: Date())
}
⬆️ Present
Presenting a modal is a bit diferent than pushing:
- create a
@State
variable for your view; - add a
Sheet
orFullScreenSheet
view with an optionalonDismiss
callback. You must add it to the view hierarchy. Don't worry they areEmptyView
s; - activate the modal with
present()
IMPORTANT NOTE: you can present a NavigationKitView
inside a Sheet
/ FullScreenSheet
?
import NavigationKit
struct Tab_1_0_View: View {
// 1.
@State private var navigationForTab_0_0_View = false
@State private var navigationForTab_1_1_View = false
@State private var navigationForTab_0_0_View_onDismiss = false
@State private var navigationForTab_1_1_View_onDismiss = false
var body: some View {
VStack {
Button {
// 3.
navigationForTab_0_0_View_onDismiss.present()
} label: {
Text("Present with onDismiss callback")
}
Button {
// 3.
navigationForTab_1_1_View_onDismiss.present()
} label: {
Text("Present with onDismiss callback")
}
Spacer()
// 2.
Sheet(isPresented: $navigationForTab_0_0_View) {
NavigationKitView {
Tab_0_0_View() // <- contains push navigation
}
}
// 2.
FullScreenSheet(isPresented: $navigationForTab_1_1_View) {
NavigationKitView {
Tab_1_1_View()
}
}
// 2.
Sheet(isPresented: $navigationForTab_0_0_View_onDismiss) {
print("Dismissed Sheet. Do something here.")
} content: {
NavigationKitView {
Tab_0_0_View()
}
}
// 2.
FullScreenSheet(isPresented: $navigationForTab_1_1_View_onDismiss) {
print("Dismissed FullScreenSheet. Do something here.")
} content: {
NavigationKitView {
Tab_1_1_View()
}
}
}
.padding()
.largeNavigationBar(titleView:
Text("Tab_1_0_View").bold().lineLimit(1),
leadingView:
Button {
// 3.
navigationForTab_0_0_View.present()
} label: {
Text("Present Navigation")
},
trailingView:
Button {
// 3.
navigationForTab_1_1_View.present()
} label: {
Text("Present")
},
backgroundView:
Color(.tertiarySystemBackground).edgesIgnoringSafeArea(.top)
)
}
}
⬇️ Dismiss
Here's how you can dismiss the modal:
- grab the
presentationMode
environment - dimiss with it's
wrappedValue
struct Tab_1_1_View: View {
// 1.
@Environment(\.presentationMode) var presentationMode
var body: some View {
VStack {
Color(.systemRed).edgesIgnoringSafeArea(.all)
}
.largeNavigationBar(titleView:
Text("Tab_1_1_View").bold().lineLimit(1),
leadingView:
Button {
// 2.
presentationMode.wrappedValue.dismiss()
} label: {
Text("Dismiss")
},
trailingView:
EmptyView(),
backgroundView:
Color(.tertiarySystemBackground).edgesIgnoringSafeArea(.top)
)
}
}
You may also disable swipe down on the Sheet
:
Sheet(isPresented: $navigationForTab_1_3_View) {
NavigationKitView {
Tab_1_3_View().disableSwipeToDismiss()
}
}
If you want to dismiss to root you want to use @Binding
s and dismiss in order. 0.25
is the optimal delay:
struct Tab_1_3_View: View {
@Environment(\.presentationMode) var presentationMode
@Binding var rootView: Bool
@Binding var secondRootView: Bool
@Binding var thirdRootView: Bool
var body: some View {
VStack {
Color(.systemRed).edgesIgnoringSafeArea(.all)
}
.largeNavigationBar(titleView:
Text("Tab_1_3_View").bold().lineLimit(1),
leadingView:
EmptyView(),
trailingView:
Button {
DispatchQueue.main.asyncAfter(deadline: .now()) {
thirdRootView.dismiss()
}
DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
secondRootView.dismiss()
}
DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
rootView.dismiss()
}
} label: {
Text("Dismiss to Root")
},
backgroundView:
Color(.tertiarySystemBackground).edgesIgnoringSafeArea(.top)
)
}
}