1# SwiftUI View Structure Reference
2 
3## Table of Contents
4 
5- [View Structure Principles](#view-structure-principles)
6- [Recommended View File Structure](#recommended-view-file-structure)
7- [Struct or Method / Computed Property?](#struct-or-method--computed-property)
8- [Prefer Modifiers Over Conditional Views](#prefer-modifiers-over-conditional-views)
9- [Extract Subviews, Not Computed Properties](#extract-subviews-not-computed-properties)
10- [@ViewBuilder](#viewbuilder)
11- [Keep View Body Simple and Avoid High-Cost Operations](#keep-view-body-simple-and-avoid-high-cost-operations)
12- [When to Extract Subviews](#when-to-extract-subviews)
13- [Container View Pattern](#container-view-pattern)
14- [Utilize Lazy Containers for Large Data Sets](#utilize-lazy-containers-for-large-data-sets)
15- [ZStack vs overlay/background](#zstack-vs-overlaybackground)
16- [Compositing Group Before Clipping](#compositing-group-before-clipping)
17- [Split State-Driven Parts into Custom View Types](#split-state-driven-parts-into-custom-view-types)
18- [Reusable Styling with ViewModifier](#reusable-styling-with-viewmodifier)
19- [Skeleton Loading with Redacted Views](#skeleton-loading-with-redacted-views)
20- [AnyView](#anyview)
21- [UIViewRepresentable Essentials](#uiviewrepresentable-essentials)
22- [Troubleshooting](#troubleshooting)
23- [Summary Checklist](#summary-checklist)
24 
25## View Structure Principles
26 
27SwiftUI's diffing algorithm compares view hierarchies to determine what needs updating. Proper view composition directly impacts performance.
28 
29## Recommended View File Structure
30 
31Use a consistent order when declaring SwiftUI views:
32 
331. Environment Properties
342. State Properties
353. Private Properties
364. Initializer (if needed)
375. Body
386. Computed Properties/Methods for Subviews
39 
40```swift
41struct ContentView: View {
42    // MARK: - Environment Properties
43    @Environment(\.colorScheme) var colorScheme
44 
45    // MARK: - State Properties
46    @Binding var isToggled: Bool
47    @State private var viewModel: SomeViewModel
48 
49    // MARK: - Private Properties
50    private let title: String = "SwiftUI Guide"
51 
52    // MARK: - Initializer (if needed)
53    init(isToggled: Binding<Bool>) {
54        self._isToggled = isToggled
55    }
56 
57    // MARK: - Body
58    var body: some View {
59        VStack {
60            header
61            content
62        }
63    }
64 
65    // MARK: - Computed Subviews
66    private var header: some View {
67        Text(title).font(.largeTitle).padding()
68    }
69 
70    private var content: some View {
71        VStack {
72            Text("Counter: \(counter)")
73        }
74    }
75}
76```
77 
78## Struct or Method / Computed Property?
79 
80If a `View` is intended to be reusable across multiple screens, encapsulate it within a separate `struct`. If its usage is confined to a single context, it can be declared as a function or computed property within the containing `View`.
81 
82However, if a view maintains state using `@State`, `@Binding`, `@ObservedObject`, `@Environment`, `@StateObject`, or similar wrappers, it should generally be a separate `struct`.
83 
84- For simple, static views: a computed property is acceptable.
85- For views requiring parameters: a method is more appropriate, but only when those parameters are stable. If parameters change per-call (e.g. inside a `ForEach` where each call receives a different item), prefer a separate `struct` so SwiftUI can diff inputs and skip body evaluation.
86- For reusable, stateful, or logically independent UI sections: prefer a dedicated `struct`.
87 
88```swift
89struct ContentView: View {
90    var titleView: some View {
91        Text("Hello from Property")
92            .font(.largeTitle)
93            .foregroundColor(.blue)
94    }
95 
96    func messageView(text: String, color: Color) -> some View {
97        Text(text)
98            .font(.title)
99            .foregroundColor(color)
100            .padding()
101    }
102 
103    var body: some View {
104        VStack {
105            titleView
106            messageView(text: "Hello from Method", color: .red)
107        }
108    }
109}
110```
111 
112## Prefer Modifiers Over Conditional Views
113 
114**Prefer "no-effect" modifiers over conditionally including views.** When you introduce a branch, consider whether you're representing multiple views or two states of the same view.
115 
116### Use Opacity Instead of Conditional Inclusion
117 
118```swift
119// Good - same view, different states
120SomeView()
121    .opacity(isVisible ? 1 : 0)
122 
123// Avoid - creates/destroys view identity
124if isVisible {
125    SomeView()
126}
127```
128 
129**Why**: Conditional view inclusion can cause loss of state, poor animation performance, and breaks view identity. Using modifiers maintains view identity across state changes.
130 
131### When Conditionals Are Appropriate
132 
133Use conditionals when you truly have **different views**, not different states:
134 
135```swift
136// Correct - fundamentally different views
137if isLoggedIn {
138    DashboardView()
139} else {
140    LoginView()
141}
142 
143// Correct - optional content
144if let user {
145    UserProfileView(user: user)
146}
147```
148 
149### Conditional View Modifier Extensions Break Identity
150 
151A common pattern is an `if`-based `View` extension for conditional modifiers. This changes the view's return type between branches, which destroys view identity and breaks animations:
152 
153```swift
154// Problematic -- different return types per branch
155extension View {
156    @ViewBuilder func `if`<T: View>(_ condition: Bool, transform: (Self) -> T) -> some View {
157        if condition {
158            transform(self)  // Returns T
159        } else {
160            self              // Returns Self
161        }
162    }
163}
164```
165 
166Prefer applying the modifier directly with a ternary or always-present modifier:
167 
168```swift
169// Good -- same view identity maintained
170Text("Hello")
171    .opacity(isHighlighted ? 1 : 0.5)
172 
173// Good -- modifier always present, value changes
174Text("Hello")
175    .foregroundStyle(isError ? .red : .primary)
176```
177 
178## Extract Subviews, Not Computed Properties
179 
180### The Problem with @ViewBuilder Functions
181 
182When you use `@ViewBuilder` functions or computed properties for complex views, the entire function re-executes on every parent state change:
183 
184```swift
185// BAD - re-executes complexSection() on every tap
186struct ParentView: View {
187    @State private var count = 0
188 
189    var body: some View {
190        VStack {
191            Button("Tap: \(count)") { count += 1 }
192            complexSection()  // Re-executes every tap!
193        }
194    }
195 
196    @ViewBuilder
197    func complexSection() -> some View {
198        // Complex views that re-execute unnecessarily
199        ForEach(0..<100) { i in
200            HStack {
201                Image(systemName: "star")
202                Text("Item \(i)")
203                Spacer()
204                Text("Detail")
205            }
206        }
207    }
208}
209```
210 
211### The Solution: Separate Structs
212 
213Extract to separate `struct` views. SwiftUI can skip their `body` when inputs don't change:
214 
215```swift
216// GOOD - ComplexSection body SKIPPED when its inputs don't change
217struct ParentView: View {
218    @State private var count = 0
219 
220    var body: some View {
221        VStack {
222            Button("Tap: \(count)") { count += 1 }
223            ComplexSection()  // Body skipped during re-evaluation
224        }
225    }
226}
227 
228struct ComplexSection: View {
229    var body: some View {
230        ForEach(0..<100) { i in
231            HStack {
232                Image(systemName: "star")
233                Text("Item \(i)")
234                Spacer()
235                Text("Detail")
236            }
237        }
238    }
239}
240```
241 
242### Why This Works
243 
2441. SwiftUI compares the `ComplexSection` struct (which has no properties)
2452. Since nothing changed, SwiftUI skips calling `ComplexSection.body`
2463. The complex view code never executes unnecessarily
247 
248## @ViewBuilder
249 
250Use `@ViewBuilder` functions for small, simple sections (a few views, no expensive computation) that don't affect performance. They work particularly well for static content that doesn't depend on any `@State` or `@Binding`, since SwiftUI won't need to diff them independently. Extract to a separate `struct` when the section is complex, depends on state, or needs to be skipped during re-evaluation.
251 
252The `@ViewBuilder` attribute is only required when a function or computed property returns multiple different views conditionally, for example through `if` or `switch`:
253 
254```swift
255@ViewBuilder
256private var conditionalView: some View {
257    if isExpanded {
258        VStack {
259            Text("Expanded View")
260            Image(systemName: "star")
261        }
262    } else {
263        Text("Collapsed View")
264    }
265}
266```
267 
268If every branch returns the same concrete type, `@ViewBuilder` is unnecessary:
269 
270```swift
271var conditionalText: some View {
272    if Bool.random() {
273        Text("Hello")
274    } else {
275        Text("World")
276    }
277}
278```
279 
280Prefer `@ViewBuilder` when:
281 
282- there is conditional branching between multiple view types
283- extracting a separate `struct` would not provide meaningful separation
284 
285## Keep View Body Simple and Avoid High-Cost Operations
286 
287Refrain from performing complex operations within the `body` of your view. Instead of passing a ready-to-use sequence with filtering, mapping, or sorting directly into `ForEach`, prepare the sequence outside the body.
288 
289```swift
290// Avoid such things ...
291var body: some View {
292    List {
293        ForEach(model.values.filter { $0 > 0 }, id: \.self) {
294            Text(String($0))
295                .padding()
296        }
297    }
298}
299```
300 
301Prefer:
302 
303```swift
304struct FilteredListView: View {
305    private let filteredValues: [Int]
306 
307    init(values: [Int]) {
308        self.filteredValues = values.filter { $0 > 0 } // Perform filtering once
309    }
310 
311    var body: some View {
312        List {
313            content
314        }
315    }
316 
317    private var content: some View {
318        ForEach(filteredValues, id: \.self) { value in
319            Text(String(value))
320                .padding()
321        }
322    }
323}
324```
325 
326The reason this matters is that the system can call `body` multiple times during a single layout phase. Complex body computation makes those calls more expensive than necessary.
327 
328General guidance:
329 
330- avoid filtering, sorting, and mapping inline in `body`
331- avoid constructing expensive formatters in `body`
332- avoid heavy branching in large view trees
333- move data preparation into init, model layer, or dedicated helpers
334 
335## When to Extract Subviews
336 
337Extract complex views into separate subviews when:
338- The view has multiple logical sections or responsibilities
339- The view contains reusable components
340- The view body becomes difficult to read or understand
341- You need to isolate state changes for performance
342- The view is becoming large (keep views small for better performance)
343- The section may evolve independently over time
344 
345## Container View Pattern
346 
347### Avoid Closure-Based Content
348 
349Closures can't be compared, causing unnecessary re-renders:
350 
351```swift
352// BAD - closure prevents SwiftUI from skipping updates
353struct MyContainer<Content: View>: View {
354    let content: () -> Content
355 
356    var body: some View {
357        VStack {
358            Text("Header")
359            content()  // Always called, can't compare closures
360        }
361    }
362}
363 
364// Usage forces re-render on every parent update
365MyContainer {
366    ExpensiveView()
367}
368```
369 
370### Use @ViewBuilder Property Instead
371 
372```swift
373// GOOD - view can be compared
374struct MyContainer<Content: View>: View {
375    @ViewBuilder let content: Content
376 
377    var body: some View {
378        VStack {
379            Text("Header")
380            content  // SwiftUI can compare and skip if unchanged
381        }
382    }
383}
384 
385// Usage - SwiftUI can diff ExpensiveView
386MyContainer {
387    ExpensiveView()
388}
389```
390 
391## Utilize Lazy Containers for Large Data Sets
392 
393When displaying extensive lists or grids, prefer `LazyVStack`, `LazyHStack`, `LazyVGrid`, or `LazyHGrid`. These containers load views only when they appear on the screen, reducing memory usage and improving performance.
394 
395```swift
396struct ContentView: View {
397    let items = Array(0..<1000)
398 
399    var body: some View {
400        ScrollView {
401            LazyVStack {
402                ForEach(items, id: \.self) { item in
403                    Text("Item \(item)")
404                }
405            }
406        }
407    }
408}
409```
410 
411Prefer lazy containers when:
412 
413- rendering large collections
414- row views are non-trivial
415- memory usage matters
416- the content is inside `ScrollView`
417 
418## ZStack vs overlay/background
419 
420Use `ZStack` to **compose multiple peer views** that should be layered together and jointly define layout.
421 
422Prefer `overlay` / `background` when you’re **decorating a primary view**.  
423Not primarily because they don’t affect layout size, but because they **express intent and improve readability**: the view being modified remains the clear layout anchor.
424 
425A key difference is **size proposal behavior**:
426- In `overlay` / `background`, the child view implicitly adopts the size proposed to the parent when it doesn’t define its own size, making decorative attachments feel natural and predictable.
427- In `ZStack`, each child participates independently in layout, and no implicit size inheritance exists. This makes it better suited for peer composition, but less intuitive for simple decoration.
428 
429Use `ZStack` (or another container) when the “decoration” **must explicitly participate in layout sizing**—for example, when reserving space, extending tappable/visible bounds, or preventing overlap with neighboring views.
430 
431### Examples
432 
433```swift
434// GOOD - decoration via overlay (layout anchored to button)
435Button("Continue") { }
436    .overlay(alignment: .trailing) {
437        Image(systemName: "lock.fill").padding(.trailing, 8)
438    }
439 
440// BAD - ZStack when overlay suffices (layout no longer anchored to button)
441ZStack(alignment: .trailing) {
442    Button("Continue") { }
443    Image(systemName: "lock.fill").padding(.trailing, 8)
444}
445 
446// GOOD - background shape takes parent size
447HStack(spacing: 12) { Text("Inbox"); Text("Next") }
448    .background { Capsule().strokeBorder(.blue, lineWidth: 2) }
449```
450 
451## Compositing Group Before Clipping
452 
453**Always add `.compositingGroup()` before `.clipShape()` when clipping layered views (`.overlay` or `.background`).** Without it, each layer is antialiased separately and then composited. Where antialiased edges overlap — typically at rounded corners — you get visible color fringes (semi-transparent pixels of different colors blending together).
454 
455```swift
456let shape = RoundedRectangle(cornerRadius: 16)
457 
458// BAD - each layer antialiased separately, producing color fringes at corners
459Color.red
460    .overlay(.white, in: shape)
461    .clipShape(shape)
462    .frame(width: 200, height: 150)
463 
464// GOOD - layers composited first, antialiasing applied once during clipping
465Color.red
466    .overlay(.white, in: .rect)
467    .compositingGroup()
468    .clipShape(shape)
469    .frame(width: 200, height: 150)
470```
471 
472`.compositingGroup()` forces all child layers to be rendered into a single offscreen buffer before the clip is applied. This means antialiasing only happens once — on the final composited result — eliminating the fringe artifacts.
473 
474## Split State-Driven Parts into Custom View Types
475 
476Large views often depend on multiple independent state sources. If a single view body depends on all of them, then any state change can cause the entire body to re-evaluate.
477 
478```swift
479struct BigAndComplicatedView: View {
480    @State private var counter = 0
481    @State private var isToggled = false
482    @StateObject private var viewModel = SomeViewModel()
483 
484    let title = "Big and Complicated View"
485 
486    var body: some View {
487        VStack {
488            Text(title)
489                .font(.largeTitle)
490 
491            Text("Counter: \(counter)")
492                .font(.title)
493 
494            Toggle("Enable Feature", isOn: $isToggled)
495                .padding()
496 
497            Button("Increment Counter") {
498                counter += 1
499            }
500 
501            Text("ViewModel Data: \(viewModel.data)")
502                .padding()
503 
504            Button("Fetch Data") {
505                viewModel.fetchData()
506            }
507        }
508    }
509}
510```
511 
512### Better: Split Into Smaller Components
513 
514```swift
515struct BigAndComplicatedView: View {
516    @State private var counter = 0
517    @State private var isToggled = false
518    @StateObject private var viewModel = SomeViewModel()
519 
520    var body: some View {
521        VStack {
522            titleView
523            CounterView(counter: $counter)
524            ToggleView(isToggled: $isToggled)
525            ViewModelDataView(data: viewModel.data) {
526                viewModel.updateData()
527            }
528            .equatable()
529        }
530    }
531 
532    private var titleView: some View {
533        Text("Big and Complicated View")
534            .font(.largeTitle)
535    }
536}
537```
538 
539Why this is better:
540 
541- changing `counter` only affects `CounterView`
542- toggling only affects `ToggleView`
543- updating the model data only affects `ViewModelDataView`
544 
545### Notes on Equatable
546 
547Using `Equatable` for a view is not a universal best practice, but it can be useful in targeted cases where:
548 
549- the input is small and well-defined
550- the comparison logic is meaningful
551- you want to reduce unnecessary body evaluation for a specific subtree
552 
553Do not use `Equatable` as a blanket optimization technique.
554 
555## Reusable Styling with ViewModifier
556 
557Extract repeated modifier combinations into a `ViewModifier` struct. Expose via a `View` extension for autocompletion:
558 
559```swift
560private struct CardStyle: ViewModifier {
561    func body(content: Content) -> some View {
562        content
563            .padding()
564            .background(Color(.secondarySystemBackground))
565            .clipShape(.rect(cornerRadius: 12))
566    }
567}
568 
569extension View {
570    func cardStyle() -> some View {
571        modifier(CardStyle())
572    }
573}
574```
575 
576### Custom ButtonStyle
577 
578Use the `ButtonStyle` protocol for reusable button designs. Use `PrimitiveButtonStyle` only when you need custom interaction handling (e.g., simultaneous gestures):
579 
580```swift
581struct PrimaryButtonStyle: ButtonStyle {
582    func makeBody(configuration: Configuration) -> some View {
583        configuration.label
584            .bold()
585            .foregroundStyle(.white)
586            .padding(.horizontal, 16)
587            .padding(.vertical, 8)
588            .background(Color.accentColor)
589            .clipShape(Capsule())
590            .scaleEffect(configuration.isPressed ? 0.95 : 1)
591            .animation(.smooth, value: configuration.isPressed)
592    }
593}
594```
595 
596### Discoverability with Static Member Lookup
597 
598Make custom styles and modifiers discoverable via leading-dot syntax:
599 
600```swift
601extension ButtonStyle where Self == PrimaryButtonStyle {
602    static var primary: PrimaryButtonStyle { .init() }
603}
604 
605// Usage: .buttonStyle(.primary)
606```
607 
608This pattern works for any SwiftUI style protocol (`ButtonStyle`, `ListStyle`, `ToggleStyle`, etc.).
609 
610## Skeleton Loading with Redacted Views
611 
612Use `.redacted(reason: .placeholder)` to show skeleton views while data loads. Use `.unredacted()` to opt out specific views:
613 
614```swift
615VStack(alignment: .leading) {
616    Text(article?.title ?? String(repeating: "X", count: 20))
617        .font(.headline)
618    Text(article?.author ?? String(repeating: "X", count: 12))
619        .font(.subheadline)
620    Text("SwiftLee")
621        .font(.caption)
622        .unredacted()
623}
624.redacted(reason: article == nil ? .placeholder : [])
625```
626 
627Apply `.redacted` on a container to redact all children at once.
628 
629## AnyView
630 
631`AnyView` is type erasure. SwiftUI uses structural identity based on type information to determine when views should be updated.
632 
633```swift
634private var nameView: some View {
635    if isEditable {
636        TextField("Your name", text: $name)
637    } else {
638        Text(name)
639    }
640}
641```
642 
643Avoid patterns like:
644 
645```swift
646private var nameView: some View {
647    if isEditable {
648        return AnyView(TextField("Your name", text: $name))
649    } else {
650        return AnyView(Text(name))
651    }
652}
653```
654 
655Because `AnyView` erases type information, SwiftUI loses some optimization opportunities. Prefer `@ViewBuilder` or conditional branches with concrete view types.
656 
657Use `AnyView` only when type erasure is truly necessary for API design.
658 
659## UIViewRepresentable Essentials
660 
661When bridging UIKit views into SwiftUI:
662 
663- `makeUIView(context:)` is called **once** to create the UIKit view
664- `updateUIView(_:context:)` is called on **every SwiftUI redraw** to sync state
665- The representable struct itself is **recreated on every redraw** -- avoid heavy work in its init
666- Use a `Coordinator` for delegate callbacks and two-way communication
667 
668```swift
669struct MapView: UIViewRepresentable {
670    let coordinate: CLLocationCoordinate2D
671 
672    func makeUIView(context: Context) -> MKMapView {
673        let map = MKMapView()
674        map.delegate = context.coordinator
675        return map
676    }
677 
678    func updateUIView(_ map: MKMapView, context: Context) {
679        map.setCenter(coordinate, animated: true)
680    }
681 
682    func makeCoordinator() -> Coordinator { Coordinator() }
683 
684    class Coordinator: NSObject, MKMapViewDelegate { }
685}
686```
687 
688## Troubleshooting
689 
690### Debug SwiftUI Renderings
691 
692If it is needed to debug render cycles and read console output you can leverage the `_printChanges()` or `_logChanges()` methods on `View`. These methods print information about when the view is being evaluated and what changes are triggering updates. This can be very helpful when your view body is called multiple times and you want to know why.
693 
694```swift
695struct ContentView: View {
696    @State private var counter: Int = 99
697 
698    init() {
699        print(Self.self, #function)
700    }
701 
702    var body: some View {
703        let _ = Self._printChanges()
704 
705        VStack {
706            Text("Counter: \(counter)")
707            Button {
708                counter += 1
709            } label: {
710                Text("Counter +1")
711            }
712            .buttonStyle(.borderedProminent)
713        }
714        .padding()
715    }
716}
717```
718 
719As an alternative to `Self._printChanges()`, you can use `_logChanges()`
720 
721```swift
722struct ContentView: View {
723    @State private var counter: Int = 99
724 
725    var body: some View {
726        let _ = Self._logChanges()
727 
728        VStack {
729            Text("Counter: \(counter)")
730            Button {
731                counter += 1
732            } label: {
733                Text("Counter +1")
734            }
735            .buttonStyle(.borderedProminent)
736        }
737        .padding()
738    }
739}
740```
741 
742Use these tools only for debugging and remove them from production code.
743 
744### Handling "The Compiler Is Unable to Type-Check This Expression in Reasonable Time"
745 
746If you encounter:
747 
748> The compiler is unable to type-check this expression in reasonable time; try breaking up the expression into distinct sub-expressions
749 
750it is often caused by overly complex view structures or expressions.
751 
752Ways to fix it:
753 
754- break large expressions into smaller computed values
755- extract subviews
756- split long modifier chains
757- simplify nested generics and builders
758- avoid huge inline closures
759 
760## Summary Checklist
761 
762- [ ] Follow a consistent view file structure (Environment → State → Private → Init → Body → Subviews)
763- [ ] Prefer modifiers over conditional views for state changes
764- [ ] Avoid `if`-based conditional modifier extensions (they break view identity)
765- [ ] Extract complex views into separate subviews, not computed properties
766- [ ] Keep views small for readability and performance
767- [ ] Use `@ViewBuilder` only where it actually adds value
768- [ ] Avoid heavy filtering, mapping, sorting, or formatter creation inside `body`
769- [ ] Use lazy containers for large data sets
770- [ ] Container views use `@ViewBuilder let content: Content`
771- [ ] Prefer `overlay` / `background` for decoration and `ZStack` for peer composition
772- [ ] `.compositingGroup()` before `.clipShape()` on layered views to avoid antialiasing fringes
773- [ ] Split state-heavy areas into smaller view types
774- [ ] Extract repeated styling into `ViewModifier` or `ButtonStyle`
775- [ ] Expose reusable styles via static member lookup when it improves discoverability
776- [ ] Use `.redacted(reason: .placeholder)` for loading skeletons
777- [ ] Avoid `AnyView` unless type erasure is truly needed
778- [ ] In `UIViewRepresentable`, keep heavy work out of struct init
779- [ ] Use `_printChanges()` / `_logChanges()` to debug rendering behavior
780- [ ] Break up overly complex expressions when the compiler struggles
781