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

ZStack

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

Lazy Stacks

Use

LazyVStack

LazyHStack

ScrollView

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

.adaptive

.flexible

// 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

GeometryReader

.onGeometryChange

See references/grids.md for full grid patterns and design choices.

List Patterns

Use

List

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)

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

ScrollView

Use

ScrollView

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:)

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

Section

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

NavigationStack

Controls

Toggle

Picker

.segmented

Slider

DatePicker

TextField

.keyboardType

.textInputAutocapitalization

Bind controls directly to

@State

@Binding

@AppStorage

Form

.disabled(...)

Label

// Toggle sections
Form {
  Section("Notifications") {
    Toggle("Mentions", isOn: $preferences.notificationsMentionsEnabled)
    Toggle("Follows", isOn: $preferences.notificationsFollowsEnabled)
  }
}

// Slider with value text
Section("Font Size") {
  Slider(value: $fontSizeScale, in: 0.5...1.5, step: 0.1)
  Text("Scale: \(String(format: "%.1f", fontSizeScale))")
}

// Picker for enums
Picker("Default Visibility", selection: $visibility) {
  ForEach(Visibility.allCases, id: \.self) { option in
    Text(option.title).tag(option)
  }
}

Avoid

.pickerStyle(.segmented)

See references/form.md for full form examples.

Searchable

Add native search UI with

.searchable

.searchScopes

.task(id:)

@MainActor
struct ExploreView: View {
  @State private var searchQuery = ""
  @State private var searchScope: SearchScope = .all
  @State private var isSearching = false
  @State private var results: [SearchResult] = []

  var body: some View {
    List {
      if isSearching {
        ProgressView()
      } else {
        ForEach(results) { result in
          SearchRow(result: result)
        }
      }
    }
    .searchable(
      text: $searchQuery,
      placement: .navigationBarDrawer(displayMode: .always),
      prompt: Text("Search")
    )
    .searchScopes($searchScope) {
      ForEach(SearchScope.allCases, id: \.self) { scope in
        Text(scope.title)
      }
    }
    .task(id: searchQuery) {
      await runSearch()
    }
  }

  private func runSearch() async {
    guard !searchQuery.isEmpty else {
      results = []
      return
    }
    isSearching = true
    defer { isSearching = false }
    try? await Task.sleep(for: .milliseconds(250))
    results = await fetchResults(query: searchQuery, scope: searchScope)
  }
}

Show a placeholder when search is empty. Debounce input to avoid overfetching. Keep search state local to the view. Avoid running searches for empty strings.

Overlay and Presentation

Use

.overlay(alignment:)

struct AppRootView: View {
  @State private var toast: Toast?

  var body: some View {
    content
      .overlay(alignment: .top) {
        if let toast {
          ToastView(toast: toast)
            .transition(.move(edge: .top).combined(with: .opacity))
            .onAppear {
              Task {
                try? await Task.sleep(for: .seconds(2))
                withAnimation { self.toast = nil }
              }
            }
        }
      }
  }
}

Prefer overlays for transient UI rather than embedding in layout stacks. Use transitions and short auto-dismiss timers. Keep overlays aligned to a clear edge (

.top

.bottom

fullScreenCover: Use

.fullScreenCover(item:)

Common Mistakes

1. Using non-lazy stacks for large collections -- causes all children to render immediately
2. Placing

   GeometryReader

   inside lazy containers -- defeats lazy loading
3. Using array indices as

   ForEach

   IDs -- causes incorrect diffing and UI bugs
4. Nesting scroll views of the same axis -- causes gesture conflicts
5. Heavy custom layouts inside

   List

   rows -- use

   ScrollView

   +

   LazyVStack

   instead
6. Missing

   .contentShape(Rectangle())

   on tappable rows -- tap area is text-only
7. Hard-coding frame dimensions for sheets -- use

   .presentationSizing

   instead
8. Running searches on empty strings -- always guard against empty queries
9. Mixing

   List

   and

   ScrollView

   in the same hierarchy -- gesture conflicts
10. Using

    .pickerStyle(.segmented)

    for large option sets -- use menu or inline styles

Review Checklist

• LazyVStack

  /

  LazyHStack

  used for large or dynamic collections
• Stable

  Identifiable

  IDs on all

  ForEach

  items (not array indices)
• No

  GeometryReader

  inside lazy containers

• List

  style matches context (

  .plain

  for feeds,

  .insetGrouped

  for settings)

• Form

  used for structured input screens (not custom stacks)

• .searchable

  debounces input with

  .task(id:)

• .refreshable

  added where data source supports pull-to-refresh
• Overlays use transitions and auto-dismiss timers

• .contentShape(Rectangle())

  on tappable rows

• @FocusState

  manages keyboard focus in forms

References

• Grid patterns: references/grids.md
• List and section patterns: references/list.md
• ScrollView and lazy stacks: references/scrollview.md
• Form patterns: references/form.md
• Architecture and state management: see

  swiftui-patterns

  skill
• Navigation patterns: see

  swiftui-navigation

  skill