johnrogers/swiftui-patterns

SwiftUI Patterns (iOS 17+)

SwiftUI 17+ removes ObservableObject boilerplate with @Observable, simplifies environment injection with @Environment, and introduces task-based async patterns. The core principle: use Apple's modern APIs instead of reactive libraries.

Overview

Quick Reference

| Need | Use (iOS 17+) | NOT | |------|---------------|-----| | Observable model | @Observable | ObservableObject | | Published property | Regular property | @Published | | Own state | @State | @StateObject | | Passed model (binding) | @Bindable | @ObservedObject | | Environment injection | environment(_:) | environmentObject(_:) | | Environment access | @Environment(Type.self) | @EnvironmentObject | | Async on appear | .task { } | .onAppear { Task {} } | | Value change | onChange(of:initial:_:) | onChange(of:perform:) |

Core Workflow

1. Use @Observable for model classes (no @Published needed)
2. Use @State for view-owned models, @Bindable for passed models
3. Use .task { } for async work (auto-cancels on disappear)
4. Use NavigationStack with NavigationPath for programmatic navigation
5. Apply .accessibilityLabel() and .accessibilityHint() to interactive elements

Reference Loading Guide

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

| Reference | Load When | |-----------|-----------| | Observable | Creating new @Observable model classes | | State Management | Deciding between @State, @Bindable, @Environment | | Environment | Injecting dependencies into view hierarchy | | View Modifiers | Using onChange, task, or iOS 17+ modifiers | | Migration Guide | Updating iOS 16 code to iOS 17+ | | MVVM Observable | Setting up view model architecture | | Navigation | Programmatic or deep-link navigation | | Performance | Lists with 100+ items or excessive re-renders | | UIKit Interop | Wrapping UIKit components (WKWebView, PHPicker) | | Accessibility | VoiceOver, Dynamic Type, accessibility actions | | Async Patterns | Loading states, refresh, background tasks | | Composition | Reusable view modifiers or complex conditional UI |

Common Mistakes

1. Over-using @Bindable for passed models — Creating @Bindable for every property causes unnecessary view reloads. Use @Bindable only for mutable model properties that need two-way binding. Read-only computed properties should use regular properties.

2. State placement errors — Putting model state in the view instead of a dedicated @Observable model causes view logic to become tangled. Always separate model and view concerns.

3. NavigationPath state corruption — Mutating NavigationPath incorrectly can leave it in inconsistent state. Use navigationDestination(for:destination:) with proper state management to avoid path corruption.

4. Missing .task cancellation — .task handles cancellation on disappear automatically, but nested Tasks don't. Complex async flows need explicit cancellation tracking to avoid zombie tasks.

5. Ignoring environment invalidation — Changing environment values at parent doesn't invalidate child views automatically. Use @Environment consistently and understand when re-renders happen based on observation.

6. UIKit interop memory leaks — UIViewRepresentable and UIViewControllerRepresentable can leak if delegate cycles aren't broken. Weak references and explicit cleanup are required.