/swiftui-layout-components

name: swiftui-layout-components
description: "Build SwiftUI layouts using stacks, grids, lists, scroll views, forms, and controls. Covers VStack/HStack/ZStack, LazyVGrid/LazyHGrid, List with sections and swipe actions, ScrollView with ScrollPosition and scroll-driven reveal surfaces, Form with validation, Toggle/Picker/Slider, .searchable, and overlay patterns. Use when building data-driven layouts, collection views, paged detail reveals, settings screens, search interfaces, or transient overlay UI."

SwiftUI Layout & Components

Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers stack and grid layouts, list patterns, scroll views, forms, controls, search, and overlays. Patterns are backward-compatible to iOS 17 unless noted.

Contents

• [Layout Fundamentals](#layout-fundamentals)
• [Grid Layouts](#grid-layouts)
• [List Patterns](#list-patterns)
• [ScrollView](#scrollview)
• [Form and Controls](#form-and-controls)
• [Searchable](#searchable)
• [Overlay and Presentation](#overlay-and-presentation)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Layout Fundamentals

Standard Stacks

Use `VStack`, `HStack`, and `ZStack` for small, fixed-size content. They render all children immediately.

VStack(alignment: .leading) {
    Text(title).font(.headline)
    Text(subtitle).font(.subheadline).foregroundStyle(.secondary)
}

Lazy Stacks

Use `LazyVStack` and `LazyHStack` inside `ScrollView` for large or dynamic collections. They create child views on demand as they scroll into view.

ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item: item)
        }
    }
    .padding(.horizontal)
}

**When to use which:**

• **Non-lazy stacks:** Small, fixed content (headers, toolbars, forms with few fields)
• **Lazy stacks:** Large or unknown-size collections, feeds, chat messages

Grid Layouts

Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections. Use `.adaptive` columns for layouts that scale across device sizes, or `.flexible` columns for a fixed column count.

// Adaptive grid -- columns adjust to fit
let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]

LazyVGrid(columns: columns) {
    ForEach(items) { item in
        ThumbnailView(item: item)
            .aspectRatio(1, contentMode: .fit)
    }
}

// Fixed 3-column grid
let columns = Array(repeating: GridItem(.flexible(minimum: 100), spacing: 4), count: 3)

LazyVGrid(columns: columns, spacing: 4) {
    ForEach(items) { item in
        ThumbnailView(item: item)
    }
}

Use `.aspectRatio` for cell sizing. Never place `GeometryReader` inside lazy containers -- it forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 16+) if you need to read dimensions.

See [references/grids.md](references/grids.md) for full grid patterns and design choices.

List Patterns

Use `List` for feed-style content and settings rows where built-in row reuse, selection, and accessibility matter.

List {
    Section("General") {
        NavigationLink("Display") { DisplaySettingsView() }
        NavigationLink("Haptics") { HapticsSettingsView() }
    }
    Section("Account") {
        Button("Sign Out", role: .destructive) { }
    }
}
.listStyle(.insetGrouped)

**Key patterns:**

• `.listStyle(.plain)` for feed layouts, `.insetGrouped` for settings
• `.scrollContentBackground(.hidden)` + custom background for themed surfaces
• `.listRowInsets(...)` and `.listRowSeparator(.hidden)` for spacing and separator control
• **Edge scrolling:** use `List` + `ScrollPosition` with `.scrollPosition($scrollPosition)` for top/bottom scroll actions
• **Item or section jumps:** use `ScrollView` + lazy stacks with `.scrollTargetLayout()` and stable targets for reliable jump-to-id behavior
• Use `.refreshable { }` for pull-to-refresh feeds
• Use `.contentShape(Rectangle())` on rows that should be tappable end-to-end
• For layout review or migration guidance, lead with container choice and constraints; keep code snippets tiny, and defer spring, transition, and timing choices to `swiftui-animation`

**iOS 26:** Apply `.scrollEdgeEffectStyle(.soft, for: .top)` for modern scroll edge effects.

See [references/list.md](references/list.md) for full list patterns including feed lists with scroll-to-top.

ScrollView

Use `ScrollView` with lazy stacks when you need custom layout, mixed content, or horizontal scrolling.

ScrollView(.horizontal, showsIndicators: false) {
    LazyHStack {
        ForEach(chips) { chip in
            ChipView(chip: chip)
        }
    }
}

**ScrollPosition:** Enables declarative, bidirectional scroll position tracking and programmatic scrolling.

@State private var scrollPosition = ScrollPosition(edge: .bottom)

ScrollView {
    LazyVStack {
        ForEach(messages) { message in
            MessageRow(message: message)
        }
    }
    .scrollTargetLayout()
}
.scrollPosition($scrollPosition)
.onChange(of: messages.last?.id) {
    withAnimation { scrollPosition.scrollTo(edge: .bottom) }
}

**`safeAreaInset(edge:)`** pins content (input bars, toolbars) above the keyboard without affecting scroll layout.

**iOS 26 additions:**

• `.scrollEdgeEffectStyle(.soft, for: .top)` -- fading edge effect
• `.backgroundExtensionEffect()` -- mirror/blur at safe area edges (use sparingly, one per screen)
• `.safeAreaBar(edge:)` -- attach bar views that integrate with scroll effects

See [references/scrollview.md](references/scrollview.md) for full `ScrollPosition`, paged reveal, zoom/crop conflict, and iOS 26 edge-effect patterns.

Form and Controls

Form

Use `Form` for structured settings and input screens. Group related controls into `Section` blocks.

Form {
    Section("Notifications") {
        Toggle("Mentions", isOn: $prefs.mentions)
        Toggle("Follows