swiftui-patterns

name	swiftui-patterns
description	Use when implementing iOS 17+ SwiftUI patterns: @Observable/@Bindable, MVVM architecture, NavigationStack, lazy loading, UIKit interop, accessibility (VoiceOver/Dynamic Type), async operations (.task/.refreshable), or migrating from ObservableObject/@StateObject.

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

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.