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
• Grid Layouts
• List Patterns
• ScrollView
• Form and Controls
• Searchable
• Overlay and Presentation
• Common Mistakes
• Review Checklist
• References

Layout Fundamentals

Standard Stacks

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

VStack(alignment: .leading, spacing: 8) {
    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(spacing: 12) {
        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, spacing: 6) {
    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 18+) if you need to read dimensions.

See 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
• Pair with ScrollViewReader for scroll-to-top or jump-to-id
• Use .refreshable { } for pull-to-refresh feeds
• Use .contentShape(Rectangle()) on rows that should be tappable end-to-end

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

See 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(spacing: 8) {
        ForEach(chips) { chip in
            ChipView(chip: chip)
        }
    }
}

ScrollViewReader: Enables programmatic scrolling to specific items.

ScrollViewReader { proxy in
    ScrollView {
        LazyVStack {
            ForEach(messages) { message in
                MessageRow(message: message).id(message.id)
            }
        }
    }
    .onChange(of: messages.last?.id) { _, newValue in
        if let id = newValue {
            withAnimation { proxy.scrollTo(id, anchor: .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 for full scroll patterns and iOS 26 edge effects.

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", isOn: $prefs.follows)
    }
    Section("Appearance") {
        Picker("Theme", selection: $theme) {
            ForEach(Theme.allCases, id: \.self) { Text($0.title).tag($0) }
        }
        Slider(value: $fontScale, in: 0.5...1.5, step: 0.1)
    }
}
.formStyle(.grouped)
.scrollContentBackground(.hidden)

Use @FocusState to manage keyboard focus in input-heavy forms. Wrap in NavigationStack only when presented standalone or in a sheet.

Controls