swiftui-navigation
Implement SwiftUI navigation patterns including NavigationStack, NavigationSplitView, sheet presentation, tab-based navigation, and deep linking
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill swiftui-navigationInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of swiftui-navigation
swiftui-navigation scores 87/100 on our quality scale, 2209th of 4,698 Development & Engineering skills we index (top 48%).
Its SKILL.md is 11 KB long, well organised into 15 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-02 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
swiftui-navigation compared with similar skills
All 4 of these similar skills score higher than swiftui-navigation; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| swiftui-navigation (this skill)by dpearson2699 | 87 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install swiftui-navigation?
- Run
npx skills add dpearson2699/swift-ios-skills --skill swiftui-navigation. The install tabs above show the steps for each supported agent. - Which AI agents does swiftui-navigation work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is swiftui-navigation safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is swiftui-navigation still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: swiftui-navigation description: "Implement SwiftUI navigation patterns including NavigationStack, NavigationSplitView, sheet presentation, tab-based navigation, and deep linking. Use when building push navigation, programmatic routing, multi-column layouts, modal sheets, tab bars, universal links, or custom URL scheme handling."
SwiftUI Navigation
Navigation patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers push navigation, multi-column layouts, sheet presentation, tab architecture, and deep linking. Patterns are backward-compatible to iOS 17 unless noted.
Contents
- NavigationStack (Push Navigation)
- NavigationSplitView (Multi-Column)
- Sheet Presentation
- Tab-Based Navigation
- Deep Links
- Common Mistakes
- Review Checklist
- References
NavigationStack (Push Navigation)
Use NavigationStack with a typed [Route] binding for programmatic push navigation. Define routes as a Hashable enum and map them with .navigationDestination(for:); this keeps the path compile-time checked. Use NavigationPath only when one stack must hold heterogeneous route value types.
enum Route: Hashable {
case item(id: Item.ID)
}
struct ContentView: View {
@State private var path: [Route] = []
let items: [Item]
var body: some View {
NavigationStack(path: $path) {
List(items) { item in
NavigationLink(value: Route.item(id: item.id)) {
ItemRow(item: item)
}
}
.navigationDestination(for: Route.self) { route in
switch route {
case .item(let id):
DetailView(itemID: id)
}
}
.navigationTitle("Items")
}
}
}
Programmatic navigation:
path.append(.item(id: item.id)) // Push
path.removeLast() // Pop one
path = [] // Pop to root
Router pattern: For apps with complex navigation, use a router object that owns the path and sheet state. Each tab gets its own router instance injected via .environment(). Centralize destination mapping with a single .navigationDestination(for:) block or a shared withAppRouter() modifier.
See references/navigationstack.md for full router examples including per-tab stacks, centralized destination mapping, and generic tab routing.
NavigationSplitView (Multi-Column)
Use NavigationSplitView for sidebar-detail layouts on iPad and Mac. Falls back to stack navigation on iPhone.
struct MasterDetailView: View {
@State private var selectedItem: Item?
var body: some View {
NavigationSplitView {
List(items, selection: $selectedItem) { item in
NavigationLink(value: item) { ItemRow(item: item) }
}
.navigationTitle("Items")
} detail: {
if let item = selectedItem {
ItemDetailView(item: item)
} else {
ContentUnavailableView("Select an Item", systemImage: "sidebar.leading")
}
}
}
}
Custom Split Column (Manual HStack)
For custom multi-column layouts (e.g., a dedicated notification column independent of selection), use a manual HStack split with horizontalSizeClass checks:
@MainActor
struct AppView: View {
@Environment(\.horizontalSizeClass) private var horizontalSizeClass
@AppStorage("showSecondaryColumn") private var showSecondaryColumn = true
var body: some View {
HStack(spacing: 0) {
primaryColumn
if shouldShowSecondaryColumn {
Divider().edgesIgnoringSafeArea(.all)
secondaryColumn
}
}
}
private var shouldShowSecondaryColumn: Bool {
horizontalSizeClass == .regular
&& showSecondaryColumn
}
private var primaryColumn: some View {
TabView { /* tabs */ }
}
private var secondaryColumn: some View {
NotificationsTab()
.environment(\.isSecondaryColumn, true)
.frame(maxWidth: .secondaryColumnWidth)
}
}
Use the manual HStack split when you need full control or a non-standard secondary column. Use NavigationSplitView when you want a standard system layout with minimal customization.
Sheet Presentation
Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model. Sheets should own their actions and call dismiss() internally.
@State private var selectedItem: Item?
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
}
Presentation sizing (iOS 18+): Control sheet dimensions with .presentationSizing:
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
.presentationSizing(.form) // .form, .page, .fitted, .automatic
}
PresentationSizing values:
.automatic-- platform default.page-- roughly paper size, for informational content.form-- slightly narrower than page, for form-style UI.fitted-- sized by the content's ideal size
Fine-tuning: .fitted(horizontal:vertical:) constrains fitting axes; .sticky(horizontal:vertical:) grows but does not shrink in specified dimensions.
Dismissal protection: On iOS/iPadOS, use .interactiveDismissDisabled(hasUnsavedChanges) and provide explicit Save/Discard actions inside the sheet. On macOS 15+, use .dismissalConfirmationDialog("Discard?", shouldPresent: hasUnsavedChanges) for window dismissal confirmation.
Route every programmatic close through the same save/validate/discard gate;
interactiveDismissDisabled guards interactive dismissal only.
Enum-driven sheet routing: Define a SheetDestination enum that is Identifiable, store it on the router, and map it with a shared view modifier. This lets any child view present sheets without prop-drilling. See references/sheets.md for the full centralized sheet routing pattern.
Tab-Based Navigation
Use the Tab API with a selection binding for scalable tab architecture. Each tab should wrap its content in an independent NavigationStack.
struct MainTabView: View {
@State private var selectedTab: AppTab = .home
var body: some View {
TabView(selection: $selectedTab) {
Tab("Home", systemImage: "house", value: .home) {
NavigationStack { HomeView() }
}
Tab("Search", systemImage: "magnifyingglass", value: .search) {
NavigationStack { SearchView() }
}
Tab("Profile", systemImage: "person", value: .profile) {
NavigationStack { ProfileView() }
}
}
}
}
Custom binding with side effects: Route selection changes through a function to intercept special tabs (e.g., compose) that should trigger an action instead of changing selection.
iOS 26 Tab Additions
Tab(value:role:)with.search-- marks a dedicated search tab with system default search title, icon, and pinning behavior.tabViewSearchActivation(_:)-- controls search tab activation and deactivation behavior.tabBarMinimizeBehavior(_:)--.onScrollDown,.onScrollUp,.never(iPhone only).tabViewSidebarHeader/Footer-- customize sidebar sections on iPadOS/macOS.tabViewBottomAccessory { }-- attach content below the tab bar (e.g., Now Playing bar)TabSection-- group tabs into sidebar sections with.tabPlacement(.sidebarOnly)
See references/tabview.md for full TabView patterns including custom bindings, dynamic tabs, and sidebar customization.
Deep Links
Use parse → validate → commit. Parse into a typed route without mutating navigation; validate scheme/host/path, identifier shape, authorization, and destination existence; then update tab/path atomically. Invalid links must leave the current navigation unchanged.
Universal Links
Universal links let iOS open your app for standard HTTPS URLs. They require:
- An Apple App Site Association (AASA) file at
/.well-known/apple-app-site-association - An Associated Domains entitlement (
applinks:example.com)
Handle Universal Links and custom URL schemes in SwiftUI with .onOpenURL:
@main
struct MyApp: App {
@State private var router = Router()
var body: some Scene {
WindowGroup {
ContentView()
.environment(router)
.onOpenURL { url in router.handle(url: url) }
}
}
}
Custom URL Schemes
Register schemes in Info.plist under CFBundleURLTypes. Handle with .onOpenURL. Prefer universal links over custom schemes for publicly shared links -- they provide web fallback and domain verification.
Handoff (NSUserActivity)
Advertise activities with .userActivity() and receive Handoff or other user activities with .onContinueUserActivity(). Declare activity types in Info.plist under NSUserActivityTypes. Set isEligibleForHandoff = true and provide a webpageURL as fallback.
See references/deeplinks.md for full examples of AASA configuration, router URL handling, custom URL schemes, and NSUserActivity continuation.
Common Mistakes
- Using deprecated
NavigationView-- useNavigationStackorNavigationSplitView - Sharing one navigation path or router across all tabs -- each tab needs its own path
- Using
.sheet(isPresented:)when state represents a model -- use.sheet(item:)instead - Storing view instances in navigation paths -- store lightweight
Hashableroute data - Nesting
@Observablerouter objects inside other@Observableobjects - Prefer
Tab(value:)withTabView(selection:)over the older.tabItem { }API - Assuming
tabBarMinimizeBehaviorworks on iPad -- it is iPhone only - Handling deep links in multiple places -- centralize URL parsing in the router
- Hard-coding sheet frame dimensions -- use
.presentationSizing(.form)instead - Missing
@MainActoron router classes -- required for Swift 6 concurrency safety
Review Checklist
- [ ]
NavigationStackused (notNavigationView) - [ ] Each tab has its own
NavigationStackwith independent path - [ ] Route enum is
Hashablewith stable identifiers - [ ]
.navigationDestination(for:)maps all route types - [ ]
.sheet(item:)preferred over.sheet(isPresented:) - [ ] Sheets own their dismiss logic internally
- [ ] Router object is
@MainActorand@Observable - [ ] Deep link URLs parsed and validated before navigation
- [ ] Universal links have AASA and Associated Domains configured
- [ ] Tab selection uses
Tab(value:)with binding
References
- NavigationStack and router patterns: references/navigationstack.md
- Sheet presentation and routing: references/sheets.md
- TabView patterns and iOS 26 API: references/tabview.md
- Deep links, universal links, and Handoff: references/deeplinks.md
- Architecture and state management: see
swiftui-patternsskill - Layout and components: see
swiftui-layout-componentsskill
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
