1# SwiftUI List Patterns Reference
2 
3## Table of Contents
4 
5- [ForEach Identity and Stability](#foreach-identity-and-stability)
6- [Enumerated Sequences](#enumerated-sequences)
7- [List with Custom Styling](#list-with-custom-styling)
8- [List with Pull-to-Refresh](#list-with-pull-to-refresh)
9- [Empty States with ContentUnavailableView (iOS 17+)](#empty-states-with-contentunavailableview-ios-17)
10- [Custom List Backgrounds](#custom-list-backgrounds)
11- [Table](#table)
12- [Summary Checklist](#summary-checklist)
13 
14## ForEach Identity and Stability
15 
16**Always provide stable identity for `ForEach`.** Never use `.indices` for dynamic content.
17 
18```swift
19// Good - stable identity via Identifiable
20extension User: Identifiable {
21    var id: String { userId }
22}
23 
24ForEach(users) { user in
25    UserRow(user: user)
26}
27 
28// Good - stable identity via keypath
29ForEach(users, id: \.userId) { user in
30    UserRow(user: user)
31}
32 
33// Wrong - indices create static content
34ForEach(users.indices, id: \.self) { index in
35    UserRow(user: users[index])  // Can crash on removal!
36}
37 
38// Wrong - unstable identity
39ForEach(users, id: \.self) { user in
40    UserRow(user: user)  // Only works if User is Hashable and stable
41}
42```
43 
44**Critical**: Ensure **constant number of views per element** in `ForEach`:
45 
46```swift
47// Good - consistent view count
48ForEach(items) { item in
49    ItemRow(item: item)
50}
51 
52// Bad - variable view count breaks identity
53ForEach(items) { item in
54    if item.isSpecial {
55        SpecialRow(item: item)
56        DetailRow(item: item)
57    } else {
58        RegularRow(item: item)
59    }
60}
61```
62 
63**Avoid inline filtering:**
64 
65```swift
66// Bad - unstable identity, changes on every update
67ForEach(items.filter { $0.isEnabled }) { item in
68    ItemRow(item: item)
69}
70 
71// Good - prefilter and cache
72@State private var enabledItems: [Item] = []
73 
74var body: some View {
75    ForEach(enabledItems) { item in
76        ItemRow(item: item)
77    }
78    .onChange(of: items) { _, newItems in
79        enabledItems = newItems.filter { $0.isEnabled }
80    }
81}
82```
83 
84**Avoid `AnyView` in list rows:**
85 
86```swift
87// Bad - hides identity, increases cost
88ForEach(items) { item in
89    AnyView(item.isSpecial ? SpecialRow(item: item) : RegularRow(item: item))
90}
91 
92// Good - Create a unified row view with a single top-level container
93ForEach(items) { item in
94    ItemRow(item: item)
95}
96 
97struct ItemRow: View {
98    let item: Item
99 
100    var body: some View {
101        // The VStack keeps the row "unary" (one top-level view) so the
102        // List can template row ids without evaluating every row's body.
103        VStack {
104            if item.isSpecial {
105                SpecialRow(item: item)
106            } else {
107                RegularRow(item: item)
108            }
109        }
110    }
111}
112```
113 
114**Why**: Stable identity is critical for performance and animations. Unstable identity causes excessive diffing, broken animations, and potential crashes.
115 
116### Prefer unary rows in `List`
117 
118`List` needs the identity of every row up front. When each row's body produces a **single top-level view** (a "unary" row), SwiftUI can template the row id from the `ForEach` element's id alone, without running each row's `body`. When the body branches between different top-level shapes — a bare top-level `switch`, a top-level `if` without `else`, or an `AnyView` — structural identity varies per row, so SwiftUI falls back to evaluating every row's body just to compute ids. That cost scales with the number of rows.
119 
120The fix is to wrap branching content in any single-root container (`VStack`, `HStack`, `ZStack`, or a custom wrapper) so the row is always exactly one top-level view, as shown above. A top-level `if` without an `else` is also "multi" (0 or 1 views); if some elements shouldn't be rows at all, filter the collection before it reaches the `ForEach` rather than producing a zero-view row.
121 
122To find non-constant row builders in an existing app, launch with `-LogForEachSlowPath YES`; SwiftUI logs each `ForEach` inside a lazy container whose row body produces a non-constant number of views.
123 
124### Keep ids stable, unique, and cheap
125 
126Three more identity rules that prevent subtle bugs:
127 
128- **The id must outlive the view and not change on edit.** Don't derive `id` from a mutable property (e.g. `var id: String { title }`). Editing the title changes the id, so SwiftUI treats it as a removal plus insertion — focus and per-row state are lost mid-edit. Use a stable `let id: UUID` or a server-assigned key.
129- **Don't synthesize a fresh id inside `body`.** `ForEach(items.map { Item(title: $0) })` creates new `UUID`s on every body pass, so the whole collection reads as replaced every update. Create ids once in storage that outlives `body` (the model layer), not inline.
130- **Keep the id cheap to hash.** Avoid `id: \.self` on a large `Hashable` struct; hashing walks every field on every diff. Use a small primitive (`UUID`, `Int`, short `String`, `URL`) and still pass the full element to the row.
131 
132### Identifiable ID Must Be Truly Unique
133 
134Non-unique IDs cause SwiftUI to treat different items as identical, leading to duplicate rendering or missing views:
135 
136```swift
137// Bug -- two articles with the same URL show identical content
138struct Article: Identifiable {
139    let title: String
140    let url: URL
141    var id: String { url.absoluteString }  // Not unique if URLs repeat!
142}
143 
144// Fix -- use a genuinely unique identifier
145struct Article: Identifiable {
146    let id: UUID
147    let title: String
148    let url: URL
149}
150```
151 
152**Classes get a default `ObjectIdentifier`-based `id`** when conforming to `Identifiable` without providing one. This is only unique for the object's lifetime and can be recycled after deallocation.
153 
154## Enumerated Sequences
155 
156**Using `.enumerated()` is fine; the index just must not be the identity.** Using `\.offset` as the id is the same anti-pattern as `\.self` on `items.indices` — the id becomes the position, not the element, so inserts and reorders reset row state and break animations. Keep the element's own identity as the id and treat the index as ordinary row data.
157 
158```swift
159// Wrong - offset is the position, not the element
160ForEach(items.enumerated(), id: \.offset) { index, item in
161    ItemRow(number: index + 1, item: item)
162}
163 
164// Correct - id comes from the element; index is just data
165ForEach(items.enumerated(), id: \.element.id) { index, item in
166    ItemRow(number: index + 1, item: item)
167}
168```
169 
170**No `Array(...)` wrapper is needed on Swift 6.1+.** As of Swift 6.1, the sequence returned by `.enumerated()` conditionally conforms to `RandomAccessCollection` when the base collection does, so `ForEach` accepts it directly. On earlier toolchains, wrap it in `Array(...)`. Favor the direct form in new code — it avoids an eager copy on every body evaluation.
171 
172## List with Custom Styling
173 
174```swift
175// Remove default background and separators
176List(items) { item in
177    ItemRow(item: item)
178        .listRowInsets(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
179        .listRowSeparator(.hidden)
180}
181.listStyle(.plain)
182.scrollContentBackground(.hidden)
183.background(Color.customBackground)
184.environment(\.defaultMinListRowHeight, 1)  // Allows custom row heights
185```
186 
187## List with Pull-to-Refresh
188 
189```swift
190List(items) { item in
191    ItemRow(item: item)
192}
193.refreshable {
194    await loadItems()
195}
196```
197 
198## Empty States with ContentUnavailableView (iOS 17+)
199 
200Use `ContentUnavailableView` for empty list/search states. The built-in `.search` variant is auto-localized:
201 
202```swift
203List {
204    ForEach(searchResults) { item in
205        ItemRow(item: item)
206    }
207}
208.overlay {
209    if searchResults.isEmpty, !searchText.isEmpty {
210        ContentUnavailableView.search(text: searchText)
211    }
212}
213```
214 
215For non-search empty states, use a custom instance:
216 
217```swift
218ContentUnavailableView(
219    "No Articles",
220    systemImage: "doc.richtext.fill",
221    description: Text("Articles you save will appear here.")
222)
223```
224 
225## Custom List Backgrounds
226 
227Use `.scrollContentBackground(.hidden)` to replace the default list background:
228 
229```swift
230List(items) { item in
231    ItemRow(item: item)
232}
233.scrollContentBackground(.hidden)
234.background(Color.customBackground)
235```
236 
237Without `.scrollContentBackground(.hidden)`, a custom `.background()` has no visible effect on `List`.
238 
239## Table
240 
241> **Availability:** iOS 16.0+, iPadOS 16.0+, visionOS 1.0+
242 
243A multi-column data container that presents rows of `Identifiable` data with sortable, selectable columns. On compact size classes (iPhone, iPad Slide Over), columns after the first are automatically hidden.
244 
245### Basic Table
246 
247```swift
248struct Person: Identifiable {
249    let givenName: String
250    let familyName: String
251    let emailAddress: String
252    let id = UUID()
253    var fullName: String { givenName + " " + familyName }
254}
255 
256struct PeopleTable: View {
257    @State private var people: [Person] = [ /* ... */ ]
258 
259    var body: some View {
260        Table(people) {
261            TableColumn("Given Name", value: \.givenName)
262            TableColumn("Family Name", value: \.familyName)
263            TableColumn("E-Mail Address", value: \.emailAddress)
264        }
265    }
266}
267```
268 
269### Table with Selection
270 
271Bind to a single `ID` for single-selection, or a `Set<ID>` for multi-selection:
272 
273```swift
274struct SelectableTable: View {
275    @State private var people: [Person] = [ /* ... */ ]
276    @State private var selectedPeople = Set<Person.ID>()
277 
278    var body: some View {
279        Table(people, selection: $selectedPeople) {
280            TableColumn("Given Name", value: \.givenName)
281            TableColumn("Family Name", value: \.familyName)
282            TableColumn("E-Mail Address", value: \.emailAddress)
283        }
284        Text("\(selectedPeople.count) people selected")
285    }
286}
287```
288 
289### Sortable Table
290 
291Provide a binding to `[KeyPathComparator]` and re-sort the data in `.onChange(of:)`:
292 
293```swift
294struct SortableTable: View {
295    @State private var people: [Person] = [ /* ... */ ]
296    @State private var sortOrder = [KeyPathComparator(\Person.givenName)]
297 
298    var body: some View {
299        Table(people, sortOrder: $sortOrder) {
300            TableColumn("Given Name", value: \.givenName)
301            TableColumn("Family Name", value: \.familyName)
302            TableColumn("E-Mail Address", value: \.emailAddress)
303        }
304        .onChange(of: sortOrder) { _, newOrder in
305            people.sort(using: newOrder)
306        }
307    }
308}
309```
310 
311**Important:** The table does **not** sort data itself — you must re-sort the collection when `sortOrder` changes.
312 
313### Adaptive Table for Compact Size Classes
314 
315On iPhone or iPad in Slide Over, only the first column is shown. Customize it to display combined information:
316 
317```swift
318struct AdaptiveTable: View {
319    @Environment(\.horizontalSizeClass) private var horizontalSizeClass
320    private var isCompact: Bool { horizontalSizeClass == .compact }
321 
322    @State private var people: [Person] = [ /* ... */ ]
323    @State private var sortOrder = [KeyPathComparator(\Person.givenName)]
324 
325    var body: some View {
326        Table(people, sortOrder: $sortOrder) {
327            TableColumn("Given Name", value: \.givenName) { person in
328                VStack(alignment: .leading) {
329                    Text(isCompact ? person.fullName : person.givenName)
330                    if isCompact {
331                        Text(person.emailAddress)
332                            .foregroundStyle(.secondary)
333                    }
334                }
335            }
336            TableColumn("Family Name", value: \.familyName)
337            TableColumn("E-Mail Address", value: \.emailAddress)
338        }
339        .onChange(of: sortOrder) { _, newOrder in
340            people.sort(using: newOrder)
341        }
342    }
343}
344```
345 
346### Table with Static Rows
347 
348Use `init(of:columns:rows:)` when rows are known at compile time:
349 
350```swift
351struct Purchase: Identifiable {
352    let price: Decimal
353    let id = UUID()
354}
355 
356struct TipTable: View {
357    let currencyStyle = Decimal.FormatStyle.Currency(code: "USD")
358 
359    var body: some View {
360        Table(of: Purchase.self) {
361            TableColumn("Base price") { purchase in
362                Text(purchase.price, format: currencyStyle)
363            }
364            TableColumn("With 15% tip") { purchase in
365                Text(purchase.price * 1.15, format: currencyStyle)
366            }
367            TableColumn("With 20% tip") { purchase in
368                Text(purchase.price * 1.2, format: currencyStyle)
369            }
370        } rows: {
371            TableRow(Purchase(price: 20))
372            TableRow(Purchase(price: 50))
373            TableRow(Purchase(price: 75))
374        }
375    }
376}
377```
378 
379### Table with Dynamic Number of Columns
380 
381> **Availability:** iOS 17.4+, iPadOS 17.4+, Mac Catalyst 17.4+, macOS 14.4+, visionOS 1.1+
382 
383If the number of columns is not known at runtime use `TableColumnForEach` to create columns based on a `RandomAccessCollection` of some data type. Either the collection’s elements must conform to `Identifiable` or you need to provide an id parameter to the `TableColumnForEach` initializer.
384 
385This can be mixed with static compile time known `TableColumn` usage.
386 
387```swift
388struct AudioChannel: Identifiable {
389    let name: String
390    let id: UUID
391}
392 
393struct AudioSample: Identifiable {
394    let id: UUID
395    let timestamp: TimeInterval
396    func level(channel: AudioChannel.ID) -> Double {
397        1
398    }
399}
400 
401@Observable
402class AudioSampleTrack {
403    let channels: [AudioChannel]
404    var samples: [AudioSample]
405}
406 
407struct ContentView: View {
408    var track: AudioSampleTrack
409 
410    var body: some View {
411        Table(track.samples) {
412            TableColumn("Timestamp (ms)") { sample in
413                Text(sample.timestamp, format: .number.scale(1000))
414                    .monospacedDigit()
415            }
416            TableColumnForEach(track.channels) { channel in
417                TableColumn(channel.name) { sample in
418                    Text(sample.level(channel: channel.id),
419                         format: .number.precision(.fractionLength(2))
420                    )
421                    .monospacedDigit()
422                }
423                .width(ideal: 70)
424                .alignment(.numeric)
425            }
426        }
427    }
428}
429```
430 
431### Table Styles
432 
433```swift
434// Inset (no borders)
435Table(people) { /* columns */ }
436    .tableStyle(.inset)
437 
438// Hide column headers
439Table(people) { /* columns */ }
440    .tableColumnHeaders(.hidden)
441```
442 
443### Platform Behavior
444 
445| Platform | Behavior |
446|----------|----------|
447| **iPadOS (regular)** | Full multi-column layout; headers and all columns visible |
448| **iPadOS (compact)** | Only the first column shown; headers hidden |
449| **iPhone (all sizes)** | Only the first column shown; headers hidden; list-like appearance |
450 
451> **Best Practice:** Prefer handling the compact size class by showing combined info in the first column. This provides a seamless transition when the size class changes (e.g., entering/exiting Slide Over on iPad).
452 
453## Summary Checklist
454 
455- [ ] ForEach uses stable identity (never `.indices` or `\.offset` for dynamic content)
456- [ ] Identifiable IDs are truly unique across all items
457- [ ] id is stable across edits (not derived from a mutable property), created outside `body`, and cheap to hash
458- [ ] Constant number of views per ForEach element; rows are unary (single top-level view)
459- [ ] No inline filtering in ForEach (prefilter and cache instead)
460- [ ] No `AnyView` in list rows
461- [ ] `.enumerated()` uses the element's id (not `\.offset`); no `Array(...)` wrapper needed on Swift 6.1+
462- [ ] Use `.refreshable` for pull-to-refresh
463- [ ] Use `ContentUnavailableView` for empty states (iOS 17+)
464- [ ] Use `.scrollContentBackground(.hidden)` for custom list backgrounds
465- [ ] `Table` adapts for compact size classes (first column shows combined info)
466- [ ] `Table` sorting re-sorts data in `.onChange(of: sortOrder)` (table doesn't sort itself)
467- [ ] `Table` data conforms to `Identifiable`
468