layout

SwiftUI Layout & Containers

The layer between "stacks and spacers" and "it scrolls like butter with 100k rows" — Apple's

Layout protocol, container composition, and the lazy-stack rules from the WWDC26 deep dive.

View identity/data-flow questions route to swiftui/data-flow.

When This Skill Activates

• "Make these buttons equal width" / measurement-dependent layout
• Building a reusable container (custom List/board/carousel) that should accept ForEach + sections
• Lazy stack jank, memory growth, scroll-position bugs, broken scroll targeting
• Programmatic scrolling, paging/snapping, scroll-linked effects
• GeometryReader causing layout loops or mangled sizing

Custom Layout protocol (not GeometryReader)

Reach for a custom Layout whenever you must **measure subviews and feed the measurement back

into layout** — GeometryReader only measures its container and can't influence the engine.

Canonical case: equal-width buttons.

• sizeThatFits: propose .unspecified to read each subview's ideal size

(subviews.map { $0.sizeThatFits(.unspecified) }); guard empty subviews;

replacingUnspecifiedDimensions() for nil proposal dimensions.

• placeSubviews: never assume origin (0,0) — use bounds.minX/midX (non-zero origins are

what make layouts composable); place(at:anchor:proposal:) with a proposal that may differ

from the ideal size (that's how equal widths happen).

• Respect spacing preferences: subviews[i].spacing.distance(to:along:), taking the larger

of conflicting preferences — matching built-in containers. No hardcoded 8s.

• Per-subview data via LayoutValueKey (+ a layoutValue convenience modifier), read as

subview[Key.self].

• Cache only after Instruments shows layout cost — it's an optimization, not a requirement.
• Switch layouts without killing identity: AnyLayout(HStackLayout()) ↔ custom layout with

.animation(_:value:) — SwiftUI sees one changing view, so state survives and it animates.

• Don't build fallbacks into the layout — wrap alternatives in ViewThatFits.

Grid decisions

| Need | Use |

|---|---|

| Static 2D with cross-row alignment | Grid/GridRow (+ gridCellColumns to span, gridColumnAlignment per column) |

| Scrollable, large content | LazyVGrid/LazyHGrid (only visible views load; one axis fixed up front) |

| "First arrangement that fits" | ViewThatFits |

Custom containers (Demystify Containers)

Make containers that compose like List does:

• API shape: a trailing @ViewBuilder var content: Content — callers can then mix static

views, ForEach, and conditionals.

• Iterate resolved children with ForEach(subviews: content); need the whole collection

(count/chunking)? Group(subviews: content) { subviews in … }.

• Internalize declared vs resolved: one declared ForEach resolves to N subviews; Group to

its children; EmptyView to zero; if conditionally. Counting declared views is a bug.

• Sections are opt-in: ForEach(sections: content), reading section.header /

section.content; check header.isEmpty before rendering the slot.

• Per-child customization via container values: extension ContainerValues { @Entry var … },

set with a convenience modifier, read via subview.containerValues. Scoping model:

**Environment flows down · Preferences flow up · container values reach only the direct

container.** Setting one on a Section styles the whole section.

Lazy stacks & scrolling performance (WWDC26 rules)

LazyVStack builds views only until the viewport fills; totals and offsets are estimated

from average placed-view size and corrected as you scroll. Everything below follows from that:

• One subview per ForEach element, always. An if inside a row (0-or-1 views) forces the

stack to keep off-screen views + their @State alive to preserve indices — and environment

changes then re-evaluate off-screen bodies. Filter at the data layer (@Query predicate);

gate auth-type conditions outside the stack.

• Never key logic off absolute scroll offset in a lazy stack (onScrollGeometryChange sees

estimates) — use onScrollTargetVisibilityChange(threshold: 0.8) for visibility triggers.

• Set up in init, not onAppear (_model = State(initialValue:)): body runs during

prefetch; onAppear fires only on-screen, throwing prefetch work away and causing

post-appearance size jumps. Start async loads in init/task.

• Don't persist meaningful state in row @State — off-screen views are eventually

released. Hoist (@State var highlighted: Set<ID> outside, @Binding down).

• scrollTransition transforms must stay inside the original frame (scale ✅; rotations

escaping the frame make views vanish early).

• Don't drive layout from onGeometryChange height feedback (content shoves, targeting

breaks) — that's the custom Layout case above.

• Nest LazyHStack inside LazyVStack freely (unscrolled rows stay unloaded) — but fix child

heights (lineLimit, explicit frames) in the horizontal stacks.

• pinnedViews: [.sectionHeaders] pins headers; infinite scroll = trailing

ProgressView().onAppear { fetchNextPage() } after the ForEach.

The scroll API map

• Snapping/paging: scrollTargetLayout() + scrollTargetBehavior(.viewAligned/.paging).
• Track/control position: scrollPosition binding; programmatic ScrollPosition +

scrollTo(id:) — works for unloaded targets if IDs map to stable one-subview elements.

• Scroll-linked effects: scrollTransition (enter/leave viewport) and visualEffect

(geometry without GeometryReader) — details in design/animation-patterns.

• Reactions: onScrollGeometryChange (fine outside lazy estimation),

onScrollVisibilityChange (autoplay/analytics).

• Performance floor: list/scroll internals were rewritten (WWDC25) — macOS lists ~6× faster at

100k+ rows, and lazy loading works in nested ScrollView+LazyVStack; profile with the

SwiftUI instrument (performance/swiftui-debugging).

Output Format

Layout review: Symptom | Rule violated | Fix — check the one-subview-per-element rule first

in any lazy-stack complaint; it explains most jank, memory growth, and targeting bugs.

References

• https://developer.apple.com/videos/play/wwdc2022/10056/ (Compose custom layouts)
• https://developer.apple.com/videos/play/wwdc2024/10146/ (Demystify SwiftUI containers)
• https://developer.apple.com/videos/play/wwdc2026/321/ (Dive into lazy stacks and scrolling)
• Related skills: swiftui/data-flow (identity/ForEach IDs), performance/swiftui-debugging, design/animation-patterns (scroll-linked effects)