SwiftUI does not expose a direct backButton modifier. The navigation bar creates its own back button automatically when you push a view with NavigationLink or NavigationStack. To show your own design you must hide the system button and provide a replacement in the toolbar, then dismiss the view yourself.
Why this happens
When you push a view onto a NavigationView or NavigationStack, SwiftUI wraps it in a UINavigationController under the hood. That controller automatically adds a back button with the previous screen’s title and a chevron. There is no API to style that button beyond tint and a few appearance proxies.
If you try to add a leading item with the old .navigationBarItems(leading:) API, you end up with two buttons: your custom view and the system back button. Using hidesBackButton: true inside navigationBarItems never worked reliably, and that entire API is deprecated since iOS 14.
The modern replacement is .toolbar with ToolbarItem(placement: .topBarLeading) combined with .navigationBarBackButtonHidden(true). You also need an explicit way to pop. SwiftUI does not pop automatically when you tap a custom view — you must call dismiss() from the \Environment(\.dismiss) action. If you hide the system button without adding a dismiss action, the view appears stuck.
A second side effect: hiding the system back button also disables the interactive swipe-back gesture. Users expect to swipe from the left edge to go back, and that gesture is tied to the system button.
How to fix it
1. Use NavigationStack + toolbar + dismiss (iOS 16+ recommended)
This is the current approach. NavigationStack replaces NavigationView, and .toolbar replaces .navigationBarItems.
Steps:
- Wrap your root view in
NavigationStack. - Push with
NavigationLink. - In the detail view, add
.navigationBarBackButtonHidden(true). - Add a
ToolbarItem(placement: .topBarLeading)with aButtonthat callsdismiss().
import SwiftUI
struct ContentView: View {
var body: some View {
NavigationStack {
NavigationLink("Go To Detail", destination: DetailView())
.font(.title)
.navigationTitle("Home")
}
}
}
struct DetailView: View {
@Environment(\.dismiss) private var dismiss
var body: some View {
VStack {
Text("Detail content")
}
.navigationTitle("Detail View")
.navigationBarBackButtonHidden(true)
.toolbar {
ToolbarItem(placement: .topBarLeading) {
Button {
dismiss()
} label: {
HStack(spacing: 4) {
Image(systemName: "arrow.left.circle")
Text("Back")
}
}
}
}
}
}
Why this works: .navigationBarBackButtonHidden(true) removes the system chevron, ToolbarItem puts your view in the exact leading slot, and @Environment(\.dismiss) pops the NavigationStack whether the view was pushed or presented. On iOS 17+ use .topBarLeading; on iOS 16 use .navigationBarLeading — both map to the same position.
You can use any label: Label, Image("ic_back"), custom HStack with text and icon. Apply .tint() on the NavigationStack or on the button to control color.
.toolbar {
ToolbarItem(placement: .topBarLeading) {
Button {
dismiss()
} label: {
HStack {
Image("ic_back")
.aspectRatio(contentMode: .fit)
Text("Go back")
}
}
.tint(.white)
}
}
2. Support older iOS with NavigationView (iOS 13 – iOS 15)
If you still support NavigationView, the same idea applies but with the older environment key.
import SwiftUI
struct SampleDetails: View {
@Environment(\.presentationMode) private var presentationMode: Binding<PresentationMode>
var btnBack: some View {
Button {
presentationMode.wrappedValue.dismiss()
} label: {
HStack {
Image("ic_back")
.aspectRatio(contentMode: .fit)
Text("Go back")
}
}
}
var body: some View {
List {
Text("sample code")
}
.navigationBarBackButtonHidden(true)
.navigationBarItems(leading: btnBack)
}
}
struct ParentView: View {
var body: some View {
NavigationView {
NavigationLink(destination: SampleDetails()) {
Text("Go to details")
}
.navigationTitle("Home")
}
}
}
On iOS 15+ you can already use @Environment(\.dismiss) even inside NavigationView, which is preferred over presentationMode. presentationMode is deprecated in iOS 16. If you can target iOS 15+, switch to dismiss() now to make migration to NavigationStack trivial.
Do not try to hide the bar entirely with .navigationBarHidden(true) just to get rid of the back button. That removes the whole navigation bar and you lose the title, toolbar, and large-title behavior. Hide only the button.
3. Keep the swipe-back gesture after hiding the system button
When you call .navigationBarBackButtonHidden(true), the UINavigationController disables interactivePopGestureRecognizer. If swipe-back is important, re-enable it.
The lightest fix is to add a view extension that reaches the underlying UINavigationController and re-enables the gesture. Add this once in your app:
import SwiftUI
extension UINavigationController: UIGestureRecognizerDelegate {
open override func viewDidLoad() {
super.viewDidLoad()
interactivePopGestureRecognizer?.delegate = self
}
public func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
return viewControllers.count > 1
}
}
A more isolated SwiftUI approach is to attach a helper in the detail view:
import UIKit
struct EnableSwipeBack: UIViewControllerRepresentable {
func makeUIViewController(context: Context) -> UIViewController {
let vc = UIViewController()
DispatchQueue.main.async {
vc.navigationController?.interactivePopGestureRecognizer?.isEnabled = true
vc.navigationController?.interactivePopGestureRecognizer?.delegate = nil
}
return vc
}
func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
}
Then in your detail view:
.background(EnableSwipeBack().frame(width: 0, height: 0))
Test on a real device — the simulator sometimes reports the gesture as working when it is not. If you do not need swipe-back, you can leave it disabled and document the change.
How to prevent it
- Use
NavigationStackfor all new code.NavigationViewis deprecated and itsnavigationBarItemsAPI behaves inconsistently with custom back buttons. - Always pair
.navigationBarBackButtonHidden(true)with a.toolbaritem that callsdismiss(). One without the other leaves you with no way back or with two buttons. - Prefer
@Environment(\.dismiss)over@Environment(\.presentationMode). It works for pushes, sheets, and full-screen covers and is not deprecated. - Put the toolbar modifier on the pushed view itself, not on the
NavigationStackor parent. Placement is evaluated per destination. - Decide on swipe-back up front. If you hide the system button, add the gesture fix immediately so QA does not file it as a regression later.
FAQ
Why does my custom back button remove the swipe-back gesture?
The system gesture is attached to the default back button. When you hide that button with .navigationBarBackButtonHidden(true), UIKit disables interactivePopGestureRecognizer. Re-enable it by setting its delegate to nil or by providing a custom UIGestureRecognizerDelegate that returns true when viewControllers.count > 1.
What is the difference between @Environment(.dismiss) and @Environment(.presentationMode)?
Both pop the current view, but presentationMode is the old API and is deprecated in iOS 16. dismiss is the modern replacement that works for NavigationStack pushes, sheets, and covers. Use dismiss() going forward; use presentationMode.wrappedValue.dismiss() only if you must support iOS 13-14.
Can I just use .navigationBarHidden(true) and build my own bar?
You can, but you lose the system navigation bar, large titles, search, and toolbar handling. You would need to recreate safe-area insets and back-swipe yourself. It is almost always better to keep the bar and only replace the leading item with .navigationBarBackButtonHidden(true) + .toolbar.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
