NavigationStack and replace your Button with a NavigationLink to push a new screen onto the stack. If you need to run validation or async work inside a Button action first, toggle an @State boolean and attach .navigationDestination(isPresented:) inside the NavigationStack.Why this happens
Developers coming from UIKit often start with a SwiftUI Button and look for an imperative call—like pushViewController(_:animated:), a custom delegate, or a reference to SceneDelegate—inside the button’s action closure. SwiftUI does not expose view controllers to push or pop manually.
Instead, SwiftUI navigation is declarative and state-driven. Screens are presented either by embedding a NavigationLink inside a navigation container (NavigationStack on iOS 16 and later, or NavigationView on earlier OS versions) or by binding a presentation modifier such as .navigationDestination(isPresented:) or .sheet(isPresented:) to a piece of @State.
When a NavigationLink or destination modifier is placed outside a NavigationStack, SwiftUI has no navigation container to push onto. A NavigationLink outside a stack renders as disabled or unresponsive, and .navigationDestination logs a runtime warning without changing screens.
How to fix it
1. Replace Button with NavigationLink inside NavigationStack
If tapping the control should immediately push a new screen without running extra logic first, you do not need a Button at all. Wrap the parent hierarchy in a NavigationStack and swap the Button for a NavigationLink.
import SwiftUI
struct ContentView: View {
var body: some View {
NavigationStack {
VStack(spacing: 20) {
Text("Hello, World")
NavigationLink {
DetailView()
} label: {
Text("Do Something")
.font(.largeTitle)
.fontWeight(.ultraLight)
}
}
.navigationTitle("Home")
}
}
}
struct DetailView: View {
var body: some View {
VStack {
Text("Detail Screen")
.font(.title)
}
.navigationTitle("Details")
}
}
NavigationStack automatically provides the top navigation bar, the push transition animation, the back button on DetailView, and the interactive swipe-back gesture on iOS.
If you want the link styled like a standard SwiftUI button—such as .borderedProminent—apply .buttonStyle(.borderedProminent) directly to the NavigationLink.
2. Navigate from a Button action using navigationDestination
When you must run code before navigating—such as validating form fields, saving data, or awaiting a network call—keep your Button, store a boolean in @State, and attach .navigationDestination(isPresented:) to a view inside the NavigationStack.
import SwiftUI
struct ContentView: View {
@State private var showDetail = false
var body: some View {
NavigationStack {
VStack(spacing: 20) {
Text("Hello, World")
Button {
// Run validation or state updates before navigating
showDetail = true
} label: {
Text("Do Something")
.font(.largeTitle)
.fontWeight(.ultraLight)
}
}
.navigationTitle("Home")
.navigationDestination(isPresented: $showDetail) {
DetailView()
}
}
}
}
Make sure .navigationDestination(isPresented:) is attached to the VStack (or another view inside the NavigationStack closure), not to the NavigationStack itself. When the user taps Back on DetailView, SwiftUI automatically resets showDetail to false.
If you want to navigate without displaying a navigation bar or back button—for instance, moving from an onboarding view to a custom screen—hide the toolbar on the views that should appear full-bleed:
DetailView()
.toolbar(.hidden, for: .navigationBar)
3. Push data-driven screens with NavigationStack path
For screens that depend on a model value or require multi-step programmatic navigation (such as popping straight back to the root screen), bind NavigationStack to a typed array or NavigationPath and use .navigationDestination(for:).
import SwiftUI
enum Route: Hashable {
case profile(userID: Int)
case settings
}
struct ContentView: View {
@State private var path: [Route] = []
var body: some View {
NavigationStack(path: $path) {
VStack(spacing: 16) {
Button("Open User Profile") {
path.append(.profile(userID: 42))
}
Button("Open Settings") {
path.append(.settings)
}
}
.navigationTitle("Home")
.navigationDestination(for: Route.self) { route in
switch route {
case .profile(let userID):
Text("Profile for user #\(userID)")
case .settings:
Button("Back to Root") {
path.removeAll()
}
}
}
}
}
}
Appending a Hashable route to path pushes the matching view; calling path.removeLast() pops one level, and path.removeAll() returns immediately to the root view.
4. Present a modal view with sheet or fullScreenCover
If the new view represents a self-contained task (like composing a message or editing settings) rather than a drill-down step in a hierarchy, present it modally with .sheet(isPresented:) instead of NavigationStack:
import SwiftUI
struct ContentView: View {
@State private var isShowingSheet = false
var body: some View {
VStack(spacing: 20) {
Button("Open Modal") {
isShowingSheet = true
}
}
.sheet(isPresented: $isShowingSheet) {
ModalDetailView()
}
}
}
struct ModalDetailView: View {
@Environment(\ .dismiss) private var dismiss
var body: some View {
VStack(spacing: 16) {
Text("Modal View")
Button("Done") {
dismiss()
}
}
}
}
On iOS, tvOS, and watchOS, you can replace .sheet with .fullScreenCover(isPresented:) when the modal must cover the entire screen and prevent swipe-to-dismiss.
5. Support iOS 15 and earlier with NavigationView
NavigationStack and .navigationDestination require iOS 16, iPadOS 16, or macOS 13. If you maintain a project with an iOS 15 deployment target, use NavigationView with .navigationViewStyle(.stack) and a hidden NavigationLink(destination:isActive:) when triggering navigation from a Button:
import SwiftUI
struct LegacyContentView: View {
@State private var willMoveToNextScreen = false
var body: some View {
NavigationView {
VStack(spacing: 20) {
Button("Do Something") {
willMoveToNextScreen = true
}
NavigationLink(
destination: DetailView(),
isActive: $willMoveToNextScreen
) {
EmptyView()
}
.hidden()
}
}
.navigationViewStyle(.stack)
}
}
Note that NavigationView, NavigationLink(destination:isActive:), and .navigationBarHidden(_:) are all deprecated starting in iOS 16. Avoid creating custom view modifiers that wrap every child screen in its own NavigationView, as nesting navigation containers breaks the navigation bar and back stack.
How to prevent it
- Declare one
NavigationStackper hierarchy. Do not wrapDetailViewin a secondNavigationStackwhen pushing it fromContentView, or you will get duplicate navigation bars. Modal sheets, however, have their own presentation hierarchy and can safely contain a freshNavigationStack. - Keep
.navigationDestinationinside theNavigationStackbody. Attaching.navigationDestinationoutsideNavigationStackprevents SwiftUI from registering the destination. - Prefer value-based links in large lists. Inside
ListorForEach, useNavigationLink(value:)paired with.navigationDestination(for:)so SwiftUI does not eagerly instantiate destination views before they are tapped. - Use
@Environment(\.dismiss)to go back programmatically. Instead of passing bindings down just to close a pushed view or modal sheet, calldismiss()inside the destination view.
FAQ
Why is my NavigationLink greyed out and not clickable?
A NavigationLink disables itself automatically when there is no enclosing NavigationStack (or NavigationSplitView) anywhere in its parent view hierarchy. Wrap the root view of that tab or window in a NavigationStack to enable it.
Do I need SceneDelegate or UIHostingController to switch root views?
No. Even for root-level transitions—such as moving from a login screen to the main app—switch views declaratively in your App struct’s WindowGroup or root view using an @State or @Observable authentication state (if auth.isLoggedIn { MainTabView() } else { LoginView() }).
How do I go back to the previous view from code in SwiftUI?
Declare @Environment(\.dismiss) private var dismiss inside the destination view and call dismiss() inside a Button action or Task. It pops the top view when inside a NavigationStack and closes the modal when presented via .sheet or .fullScreenCover.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
