home / skills / hoangnguyen0403 / agent-skills-standard / ios-navigation

ios-navigation skill

safe

This skill guides iOS navigation in SwiftUI using NavigationStack and deep linking, improving app reliability and user flow.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill ios-navigation

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.2 KB

---
name: iOS Navigation
description: SwiftUI navigation and deep linking using NavigationStack and Universal Links.
metadata:
  labels: [ios, swiftui, navigation, deep-linking, universal-links]
  triggers:
    files: ['**/*View.swift', '**/*App.swift']
    keywords:
      [
        NavigationStack,
        NavigationLink,
        onOpenURL,
        universalLink,
        NSUserActivity,
      ]
---

# iOS Navigation (SwiftUI)

## **Priority: P2 (OPTIONAL)**

SwiftUI path-based navigation and deep linking.

## Guidelines

- **Stack**: Use `NavigationStack` (iOS 16+) with `NavigationPath` for programmatic control.
- **Deep Links**: Handle `onOpenURL` at the Root View (`WindowGroup`).
- **Universal Links**: Configure Associated Domains (`applinks`) in Entitlements.
- **Tabs**: Maintain separate `NavigationStack` instances per `TabItem`.

[Navigation Patterns](references/swiftui-navigation.md)

## Anti-Patterns

- **No Force Unwrapping**: Use `guard let` when parsing URL components.
- **No Broken Back Stack**: Ensure valid path state before appending destinations.
- **No Missing Validation**: Check content availability before deep-link navigation.

## Related Topics

ios-design-system | ios-notifications | mobile-ux-core

Overview

This skill teaches SwiftUI navigation and deep linking patterns focused on NavigationStack, NavigationPath, and Universal Links. It packages clear, actionable guidance for building predictable in-app navigation, handling external URLs, and maintaining per-tab navigation state. The goal is reliable programmatic control and safe URL handling across iOS 16+ apps.

How this skill works

It recommends using NavigationStack with a NavigationPath for programmatic pushes, pops, and state restoration. Deep links are parsed and routed at the root WindowGroup via onOpenURL, while Universal Links require applinks entries in the entitlements. Tabs should own their own NavigationStack so each tab preserves an independent back stack.

When to use it

When you need programmatic navigation control and state restoration on iOS 16+.
When supporting deep links coming from other apps, emails, or web links.
When implementing Universal Links that open app content directly.
When your app uses tabs and must preserve separate navigation histories per tab.
When you want to avoid brittle view hierarchies and offer predictable back navigation.

Best practices

Use NavigationStack and NavigationPath for all programmatic navigation to keep state explicit.
Handle onOpenURL at the root level and route or enqueue navigation actions safely.
Validate URL components with guard let and avoid force unwrapping when parsing links.
Ensure destination content exists before appending to the NavigationPath to avoid broken back stacks.
Configure Associated Domains with applinks in entitlements for Universal Links and test both cold and warm app launches.

Example use cases

Deep-linking an email link to open a specific product page using onOpenURL and NavigationPath.
Maintaining independent navigation history for each tab in a tabbed app so switching tabs preserves state.
Restoring navigation state after app termination by serializing the NavigationPath and rehydrating on launch.
Receiving a Universal Link that routes to a nested view while validating resource availability before navigation.
Queuing incoming URLs while the app initializes, then resolving them once required data is ready.

FAQ

Should I use NavigationView or NavigationStack?

Prefer NavigationStack on iOS 16+ for programmatic control and NavigationPath; NavigationView is legacy and has limited path-based APIs.

Where do I handle incoming URLs?

Handle incoming URLs at the root WindowGroup with onOpenURL so all routing decisions and state checks happen centrally.