1# SwiftUI Layout Best Practices Reference
2 
3## Table of Contents
4 
5- [Relative Layout Over Constants](#relative-layout-over-constants)
6- [Context-Agnostic Views](#context-agnostic-views)
7- [Own Your Container](#own-your-container)
8- [Layout Performance](#layout-performance)
9- [View Logic and Testability](#view-logic-and-testability)
10- [Full-Width Views](#full-width-views)
11- [Action Handlers](#action-handlers)
12- [Summary Checklist](#summary-checklist)
13 
14## Relative Layout Over Constants
15 
16**Use dynamic layout calculations instead of hard-coded values.**
17 
18```swift
19// Good - relative to actual layout
20GeometryReader { geometry in
21    VStack {
22        HeaderView()
23            .frame(height: geometry.size.height * 0.2)
24        ContentView()
25    }
26}
27 
28// Avoid - magic numbers that don't adapt
29VStack {
30    HeaderView()
31        .frame(height: 150)  // Doesn't adapt to different screens
32    ContentView()
33}
34```
35 
36**Why**: Hard-coded values don't account for different screen sizes, orientations, or dynamic content (like status bars during phone calls).
37 
38## Context-Agnostic Views
39 
40**Views should work in any context.** Never assume presentation style or screen size.
41 
42```swift
43// Good - adapts to given space
44struct ProfileCard: View {
45    let user: User
46    
47    var body: some View {
48        VStack {
49            Image(user.avatar)
50                .resizable()
51                .aspectRatio(contentMode: .fit)
52            Text(user.name)
53            Spacer()
54        }
55        .padding()
56    }
57}
58 
59// Avoid - assumes full screen
60struct ProfileCard: View {
61    let user: User
62    
63    var body: some View {
64        VStack {
65            Image(user.avatar)
66                .frame(width: UIScreen.main.bounds.width)  // Wrong!
67            Text(user.name)
68        }
69    }
70}
71```
72 
73**Why**: Views should work as full screens, modals, sheets, popovers, or embedded content.
74 
75## Own Your Container
76 
77**Custom views should own static containers but not lazy/repeatable ones.**
78 
79```swift
80// Good - owns static container
81struct HeaderView: View {
82    var body: some View {
83        HStack {
84            Image(systemName: "star")
85            Text("Title")
86            Spacer()
87        }
88    }
89}
90 
91// Avoid - missing container
92struct HeaderView: View {
93    var body: some View {
94        Image(systemName: "star")
95        Text("Title")
96        // Caller must wrap in HStack
97    }
98}
99 
100// Good - caller owns lazy container
101struct FeedView: View {
102    let items: [Item]
103    
104    var body: some View {
105        LazyVStack {
106            ForEach(items) { item in
107                ItemRow(item: item)
108            }
109        }
110    }
111}
112```
113 
114## Layout Performance
115 
116### Avoid Layout Thrash
117 
118**Minimize deep view hierarchies and excessive layout dependencies.**
119 
120```swift
121// Bad - deep nesting, excessive layout passes
122VStack {
123    HStack {
124        VStack {
125            HStack {
126                VStack {
127                    Text("Deep")
128                }
129            }
130        }
131    }
132}
133 
134// Good - flatter hierarchy
135VStack {
136    Text("Shallow")
137    Text("Structure")
138}
139```
140 
141**Avoid excessive `GeometryReader` and preference chains:**
142 
143```swift
144// Bad - multiple geometry readers cause layout thrash
145GeometryReader { outerGeometry in
146    VStack {
147        GeometryReader { innerGeometry in
148            // Layout recalculates multiple times
149        }
150    }
151}
152 
153// Good - single geometry reader or use alternatives (iOS 17+)
154containerRelativeFrame(.horizontal) { width, _ in
155    width * 0.8
156}
157```
158 
159**Gate frequent geometry updates:**
160 
161```swift
162// Bad - updates on every pixel change
163.onPreferenceChange(ViewSizeKey.self) { size in
164    currentSize = size
165}
166 
167// Good - gate by threshold
168.onPreferenceChange(ViewSizeKey.self) { size in
169    let difference = abs(size.width - currentSize.width)
170    if difference > 10 {  // Only update if significant change
171        currentSize = size
172    }
173}
174```
175 
176## View Logic and Testability
177 
178### Keep Business Logic in Services and Models
179 
180**Business logic belongs in services and models, not in views.** Views should stay simple and declarative — orchestrating UI state, not implementing business rules. This makes logic independently testable without requiring view instantiation.
181 
182> **iOS 17+**: Use `@Observable` with `@State`.
183 
184```swift
185@Observable
186final class AuthService {
187    var email = ""
188    var password = ""
189    var isValid: Bool {
190        !email.isEmpty && password.count >= 8
191    }
192 
193    func login() async throws {
194        // Business logic here — testable without the view
195    }
196}
197 
198struct LoginView: View {
199    @State private var authService = AuthService()
200 
201    var body: some View {
202        Form {
203            TextField("Email", text: $authService.email)
204            SecureField("Password", text: $authService.password)
205            Button("Login") {
206                Task {
207                    try? await authService.login()
208                }
209            }
210            .disabled(!authService.isValid)
211        }
212    }
213}
214```
215 
216For iOS 16 and earlier, use `ObservableObject` with `@StateObject` -- see `state-management.md` for the legacy pattern.
217 
218Avoid embedding business logic directly in view closures (e.g., validation checks inside a `Button` action). This makes logic untestable without view instantiation.
219 
220**Note**: This is about making business logic testable, not about enforcing a specific architecture. The key is that logic lives outside views where it can be tested independently.
221 
222## Full-Width Views
223 
224**When a single view needs to fill the available width, use `.frame(maxWidth: .infinity, alignment:)` instead of wrapping it in a stack with a `Spacer`.**
225 
226```swift
227// Good - frame modifier
228Text("Hello")
229    .frame(maxWidth: .infinity, alignment: .leading)
230 
231// Avoid - unnecessary stack and spacer
232HStack {
233    Text("Hello")
234    Spacer()
235}
236```
237 
238**Why**: `.frame(maxWidth:alignment:)` is a single modifier that clearly communicates intent. Wrapping in an `HStack` with a `Spacer` adds an extra container to the view hierarchy for no benefit.
239 
240## Action Handlers
241 
242**Separate layout from logic.** View body should reference action methods, not contain inline logic.
243 
244```swift
245// Good - action references method
246Button("Publish Project", action: publishService.handlePublish)
247 
248// Avoid - multi-line logic in closure
249Button("Publish Project") {
250    isLoading = true
251    apiService.publish(project) { result in /* ... */ }
252}
253```
254 
255## Summary Checklist
256 
257- [ ] Use relative layout over hard-coded constants
258- [ ] Views work in any context (don't assume screen size)
259- [ ] Custom views own static containers
260- [ ] Avoid deep view hierarchies (layout thrash)
261- [ ] Gate frequent geometry updates by thresholds
262- [ ] Business logic kept in services and models (not in views)
263- [ ] Action handlers reference methods, not inline logic
264- [ ] Use `.frame(maxWidth: .infinity, alignment:)` for full-width views (not `HStack` + `Spacer`)
265- [ ] Avoid excessive `GeometryReader` usage
266- [ ] Use `containerRelativeFrame()` when appropriate
267