1# SwiftUI Previews Reference
2 
3## Table of Contents
4 
5- [Preview Macro](#preview-macro)
6- [Preview with Mock Data](#preview-with-mock-data)
7- [@Previewable Property Wrappers](#previewable-property-wrappers)
8- [Common Diagnostics](#common-diagnostics)
9- [Summary Checklist](#summary-checklist)
10 
11---
12 
13## Preview Macro
14 
15The `#Preview` macro (Swift 5.9+, Xcode 15+) is the modern way to declare previews. The legacy `PreviewProvider` protocol still works; prefer `#Preview` for new code because it's less verbose and supports inline traits.
16 
17### Basic Usage
18 
19```swift
20// Modern: #Preview macro
21#Preview {
22    ContentView()
23}
24 
25// Named preview
26#Preview("Dark Mode") {
27    ContentView()
28        .preferredColorScheme(.dark)
29}
30 
31// Legacy: PreviewProvider — still valid, but verbose for new code
32struct ContentView_Previews: PreviewProvider {
33    static var previews: some View {
34        ContentView()
35    }
36}
37```
38 
39### Multiple Previews
40 
41Declare one `#Preview` per meaningful state so each renders independently in the canvas:
42 
43```swift
44#Preview("Default") {
45    SettingsRow(title: "Notifications", isOn: true)
46}
47 
48#Preview("Off State") {
49    SettingsRow(title: "Notifications", isOn: false)
50}
51 
52#Preview("Long Title") {
53    SettingsRow(title: "Enable Push Notifications for All Events", isOn: true)
54}
55```
56 
57### Preview Traits
58 
59Traits configure the preview environment without modifying the view itself:
60 
61```swift
62// Fixed size
63#Preview(traits: .fixedLayout(width: 300, height: 100)) {
64    CompactBanner(message: "Welcome")
65}
66 
67// Size that fits content
68#Preview(traits: .sizeThatFitsLayout) {
69    BadgeView(count: 5)
70}
71 
72// Landscape orientation
73#Preview(traits: .landscapeLeft) {
74    DashboardView()
75}
76```
77 
78### Previewing Inside NavigationStack
79 
80Wrap previewed destinations in their navigation container so toolbar items, titles, and back buttons render correctly:
81 
82```swift
83#Preview {
84    NavigationStack {
85        DetailView(item: .sample)
86    }
87}
88```
89 
90---
91 
92## Preview with Mock Data
93 
94Previews must compile and render without external dependencies. Live services, network calls, and disk I/O make previews slow, flaky, or broken; use self-contained sample data instead.
95 
96### Static Sample Data
97 
98Expose sample values as static properties on the model itself so any preview can reuse them without reconstructing values inline:
99 
100```swift
101struct Item: Identifiable {
102    let id: UUID
103    var name: String
104    var price: Double
105}
106 
107extension Item {
108    static let sample = Item(id: UUID(), name: "Widget", price: 9.99)
109 
110    static let samples: [Item] = [
111        Item(id: UUID(), name: "Widget", price: 9.99),
112        Item(id: UUID(), name: "Gadget", price: 19.99),
113        Item(id: UUID(), name: "Doohickey", price: 4.99),
114    ]
115}
116 
117#Preview {
118    ItemListView(items: Item.samples)
119}
120```
121 
122### Mock Observable Models
123 
124For views driven by an `@Observable` model (see `state-management.md` for fundamentals), expose pre-configured instances on the model itself:
125 
126```swift
127@Observable
128@MainActor
129final class CartModel {
130    var items: [Item] = []
131    var isLoading = false
132 
133    static var preview: CartModel {
134        let model = CartModel()
135        model.items = Item.samples
136        return model
137    }
138 
139    static var emptyPreview: CartModel {
140        CartModel()
141    }
142 
143    static var loadingPreview: CartModel {
144        let model = CartModel()
145        model.isLoading = true
146        return model
147    }
148}
149 
150#Preview("With Items") {
151    CartView()
152        .environment(CartModel.preview)
153}
154 
155#Preview("Empty") {
156    CartView()
157        .environment(CartModel.emptyPreview)
158}
159 
160#Preview("Loading") {
161    CartView()
162        .environment(CartModel.loadingPreview)
163}
164```
165 
166### Preview with Environment Dependencies
167 
168Inject any environment values the view depends on so the preview reflects a realistic runtime context:
169 
170```swift
171#Preview {
172    OrderDetailView(order: .sample)
173        .environment(CartModel.preview)
174        .environment(\.locale, Locale(identifier: "ja_JP"))
175        .environment(\.dynamicTypeSize, .xxxLarge)
176}
177```
178 
179### Mocking Async Data Sources
180 
181When a view depends on a network or data service, give the dependency a protocol abstraction so previews can inject a synchronous mock that returns sample data immediately. This is one approach — adapt it to whatever pattern the surrounding codebase already uses.
182 
183```swift
184protocol DataFetching {
185    func fetchItems() async throws -> [Item]
186}
187 
188struct LiveDataFetcher: DataFetching {
189    let url: URL
190 
191    func fetchItems() async throws -> [Item] {
192        let (data, _) = try await URLSession.shared.data(from: url)
193        return try JSONDecoder().decode([Item].self, from: data)
194    }
195}
196 
197struct MockDataFetcher: DataFetching {
198    var result: Result<[Item], Error> = .success(Item.samples)
199 
200    func fetchItems() async throws -> [Item] {
201        try result.get()
202    }
203}
204 
205#Preview {
206    ItemListView(fetcher: MockDataFetcher())
207}
208 
209#Preview("Error State") {
210    ItemListView(fetcher: MockDataFetcher(result: .failure(URLError(.notConnectedToInternet))))
211}
212```
213 
214---
215 
216## @Previewable Property Wrappers
217 
218`@Previewable` (iOS 18+, Xcode 16+) lets you use `@State`, `@FocusState`, and other property wrappers directly inside a `#Preview` block, removing the need for a wrapper view to host interactive state.
219 
220### Interactive State
221 
222```swift
223// @Previewable: interactive toggle inline in the preview
224#Preview {
225    @Previewable @State var isOn = false
226    Toggle("Notifications", isOn: $isOn)
227}
228 
229// Without @Previewable: requires a wrapper view
230struct TogglePreviewWrapper: View {
231    @State private var isOn = false
232    var body: some View {
233        Toggle("Notifications", isOn: $isOn)
234    }
235}
236 
237#Preview {
238    TogglePreviewWrapper()
239}
240```
241 
242### Multiple Interactive Controls
243 
244```swift
245#Preview {
246    @Previewable @State var name = "Alice"
247    @Previewable @State var age = 25.0
248 
249    VStack {
250        TextField("Name", text: $name)
251        Slider(value: $age, in: 0...100, step: 1) {
252            Text("Age: \(Int(age))")
253        }
254        Text("Hello, \(name)! Age: \(Int(age))")
255    }
256    .padding()
257}
258```
259 
260### @Previewable with @FocusState
261 
262When seeding initial focus inside a preview, prefer `.defaultFocus` over writing to `@FocusState` from `.onAppear`. `.onAppear` can race the initial render and the focus assignment may be lost. See `focus-patterns.md` for the underlying rationale.
263 
264```swift
265#Preview {
266    @Previewable @FocusState var isFocused: Bool
267 
268    TextField("Search", text: .constant(""))
269        .focused($isFocused)
270        .defaultFocus($isFocused, true)
271}
272```
273 
274### Fallback for Pre-iOS 18 Targets
275 
276If the project's minimum deployment target is below iOS 18, `@Previewable` is unavailable. Fall back to a wrapper view:
277 
278```swift
279private struct SliderPreview: View {
280    @State private var value = 0.5
281    var body: some View {
282        CustomSlider(value: $value)
283    }
284}
285 
286#Preview {
287    SliderPreview()
288}
289```
290 
291---
292 
293## Common Diagnostics
294 
295| Symptom | Cause | Fix |
296|---|---|---|
297| `#Preview` body type mismatch | The closure returns a non-`View` type | Make sure the final expression is a `View` |
298| `@Previewable` only available in iOS 18+ | Using `@Previewable` with a lower deployment target | Use a wrapper view, or gate with `#available` |
299| Preview crashes with "missing environment" | An `@Environment(SomeType.self)` value is not injected | Add `.environment(SomeType.preview)` to the preview |
300| Preview hangs or renders blank | View depends on async data that never resolves | Inject a mock that returns immediately with sample data |
301| `@MainActor`-isolated model accessed from non-isolated context | A preview helper touches main-actor-only API off the main actor | Mark the helper or the preview body `@MainActor` |
302 
303---
304 
305## Summary Checklist
306 
307- [ ] Prefer `#Preview` for new previews; `PreviewProvider` is still valid for older code
308- [ ] Provide a named preview for each meaningful state (default, empty, error, loading)
309- [ ] Use `@Previewable` for interactive previews when targeting iOS 18+; wrapper views otherwise
310- [ ] Expose static `.sample` / `.preview` data on models so previews don't reconstruct values inline
311- [ ] Inject mock services through a protocol when a view depends on async data
312- [ ] Never depend on live network or disk I/O in a preview
313- [ ] Prefer `.defaultFocus` over `.onAppear` writes when seeding `@FocusState` in previews
314