Common application tasks
Start with what the application needs to do. These paths lead to a working pattern, then the API details and platform constraints. For complete running apps, use the example gallery.
| I want to… | Use this pattern | Check before shipping |
|---|---|---|
| Open a detail and return to the same list | First app, push / back | Keep query state in the retained list page; visibility is not mounting |
| Ask before losing an edit | Conditional leave guard | Activate only while dirty; iOS swipe-back is disabled while the guard is active |
| Return a selected or edited value | pushForResult and back({ result }) | Handle undefined for cancellation; generic T is not runtime validation |
| Require login before a destination | Global or route guards | Redirect to an allowed route; a leave guard does not run just because another page is pushed |
| Keep separate histories for top-level destinations | Named stacks in tabs | A drawer alone does not create one stack per menu item |
| Keep a menu visible in a wide window | Adaptive drawer | Measure the container width; permanent pane visibility differs from overlay open |
| Show list and detail together | Split navigation | Choose Frame split or UIKit split; follow the documented root/container constraints |
| Share an action between header and menu | Page actions | The app still owns business operations, confirmations and permissions |
| Search within a retained page | Native search | Search query is application state; typing does not add navigation entries |
| Open a destination from an OS link | Deep links | Configure the native manifest/entitlements, route mapping and target stack |
| Receive an image or system document | Native flows | Distinguish cancellation from failure and respect page/window ownership |
| Recover after the OS kills the app | State restoration | Persist serializable app state; JavaScript Promises do not survive process death |
| Return accessible focus after a modal | Navigation focus | Provide stable native target IDs and test with actual assistive technology |
| Explain a failed or slow navigation | Diagnostics and report viewer | Export from the affected app; synthetic sample reports are not device benchmarks |
Choose the next level of detail
- Learn a full flow: first app, then Fieldnotes.
- Find copyable native patterns: feature cookbook.
- Look up a method or type: API reference.
- Decide whether a capability fits a platform: capability map and compatibility.
When optional features help
File routes can replace a large explicit route table; layouts and middleware organize shared conventions. Route loaders, native Suspense, windows and custom hosts/destinations remain experimental where marked. Add them for a concrete application requirement after the basic navigation flow is working.