Swiftui Patterns
SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices. Use when building or reviewing SwiftUI views, @Observable state, navigation, or render performance.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Swiftui Patterns when an AI agent needs a reusable SKILL.md workflow for this job: SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices. Use when building or reviewing SwiftUI views, @Observable state, navigation, or render performance.
When not to use it
Skip Swiftui Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/swiftui-patterns # Save SKILL.md to ~/.claude/skills/swiftui-patterns/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/swiftui-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/swiftui-patterns/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Swiftui Patterns skill for this task: Use Swiftui Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# SwiftUI Patterns
Modern SwiftUI patterns for building declarative, performant user interfaces on Apple platforms. Covers the Observation framework, view composition, type-safe navigation, and performance optimization.
## When to Activate
- Building SwiftUI views and managing state (`@State`, `@Observable`, `@Binding`) - Designing navigation flows with `NavigationStack` - Structuring view models and data flow - Optimizing rendering performance for lists and complex layouts - Working with environment values and dependency injection in SwiftUI
## State Management
### Property Wrapper Selection
Choose the simplest wrapper that fits:
| Wrapper | Use Case | |---------|----------| | `@State` | View-local value types (toggles, form fields, sheet presentation) | | `@Binding` | Two-way reference to parent's `@State` | | `@Observable` class + `@State` | Owned model with multiple properties | | `@Observable` class (no wrapper) | Read-only reference passed from parent | | `@Bindable` | Two-way binding to an `@Observable` property | | `@Environment` | Shared dependencies injected via `.environment()` |
### @Observable ViewModel
Use `@Observable` (not `ObservableObject`) — it tracks property-level changes so SwiftUI only re-renders views that read the changed property:
```swift @Observable final class ItemListViewModel { private(set) var items: [Item] = [] private(set) var isLoading = false var searchText = ""
private let repository: any ItemRepository
init(repository: any ItemRepository = DefaultItemRepository()) { self.repository = repository }
func load() async { isLoading = true defer { isLoading = false } items = (try? await repository.fetchAll()) ?? [] } } ```
### View Consuming the ViewModel
```swift struct ItemListView: View { @State private var viewModel: ItemListViewModel
init(viewModel: ItemListViewModel = ItemListViewModel()) { _viewModel = State(initialValue: viewModel) }
var body: some View { List(viewModel.items) { item in ItemRow(item: item) } .searchable(text: $viewModel.searchText) .overlay { if viewModel.isLoading { ProgressView() } } .task { await viewModel.load() } } } ```
### Environment Injection
Replace `@EnvironmentObject` with `@Environment`:
```swift // Inject ContentView() .environment(authManager)
// Consume struct ProfileView: View { @Environment(AuthManager.self) private var auth
var body: some View { Text(auth.currentUser?.name ?? "Guest") } } ```
## View Composition
### Extract Subviews to Limit Invalidation
Break views into small, focused structs. When state changes, only the subview reading that state re-renders:
```swift struct OrderView: View { @State private var viewModel = OrderViewModel()
var body: some View { VStack { OrderHeader(title: viewModel.title) OrderItemList(items: viewModel.items) OrderTotal(total: viewModel.total) } } } ```
### ViewModifier for Reusable Styling
```swift struct CardModifier: ViewModifier { func body(content: Content) -> some View { content .padding() .background(.regularMaterial) .clipShape(RoundedRectangle(cornerRadius: 12)) } }
extension View { func cardStyle() -> some View { modifier(CardModifier()) } } ```
## Navigation
### Type-Safe NavigationStack
Use `NavigationStack` with `NavigationPath` for programmatic, type-safe routing:
```swift @Observable final class Router { var path = NavigationPath()
func navigate(to destination: Destination) { path.append(destination) }
func popToRoot() { path = NavigationPath() } }
enum Destination: Hashable { case detail(Item.ID) case settings case profile(User.ID) }
struct RootView: View { @State private var router = Router()
var body: some View { NavigationStack(path: $router.path) { HomeView() .navigationDestination(for: Destination.self) { dest in switch dest { case .detail(let id): ItemDetailView(itemID: id) case .settings: SettingsView() case .profile(let id): ProfileView(userID: id) } } } .environment(router) } } ```
## Performance
### Use Lazy Containers for Large Collections
`LazyVStack` and `LazyHStack` create views only when visible:
```swift ScrollView { LazyVStack(spacing: 8) { ForEach(items) { item in ItemRow(item: item) } } } ```
### Stable Identifiers
Always use stable, unique IDs in `ForEach` — avoid using array indices:
```swift // Use Identifiable conformance or explicit id ForEach(items, id: \.stableID) { item in ItemRow(item: item) } ```
### Avoid Expensive Work in body
- Never perform I/O, network calls, or heavy computation inside `body` - Use `.task {}` for async work — it cancels automatically when the view disappears - Use `.sensoryFeedback()` and `.geometryGroup()` sparingly in scroll views - Minimize `.shadow()`, `.blur()`, and `.mask()` in lists — they trigger offscreen rendering
### Equatable Conformance
For views with expensive bodies, conform to `Equatable` to skip unnecessary re-renders:
```swift struct ExpensiveChartView: View, Equatable { let dataPoints: [DataPoint] // DataPoint must conform to Equatable
static func == (lhs: Self, rhs: Self) -> Bool { lhs.dataPoints == rhs.dataPoints }
var body: some View { // Complex chart rendering } } ```
## Previews
Use `#Preview` macro with inline mock data for fast iteration:
```swift #Preview("Empty state") { ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository())) }
#Preview("Loaded") { ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository())) } ```
## Anti-Patterns to Avoid
- Using `ObservableObject` / `@Published` / `@StateObject` / `@EnvironmentObject` in new code — migrate to `@Observable` - Putting async work directly in `body` or `init` — use `.task {}` or explicit load methods - Creating view models as `@State` inside child views that don't own the data — pass from parent instead - Using `AnyView` type erasure — prefer `@ViewBuilder` or `Group` for conditional views - Ignoring `Sendable` requirements when passing data to/from actors
## References
See skill: `swift-actor-persistence` for actor-based persistence patterns. See skill: `swift-protocol-di-testing` for protocol-based DI and testing with Swift Testing.
Intended uses
- Use Swiftui Patterns when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.