swiftui-layout-components

SwiftUI Layout & Components Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.2. 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 Control Usage Toggle Boolean preferences Picker Discrete choices; .segmented for 2-4 options Slider Numeric ranges with visible value label DatePicker Date/time selection TextField Text input with .keyboardType , .textInputAutocapitalization Bind controls directly to @State , @Binding , or @AppStorage . Group related controls in Form sections. Use .disabled(...) to reflect locked or inherited settings. Use Label inside toggles to combine icon + text when it adds clarity. // 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) for large sets; use menu or inline styles. Don't hide labels for sliders; always show context. See references/form.md for full form examples. Searchable Add native search UI with .searchable . Use .searchScopes for multiple modes and .task(id:) for debounced async results. @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:) for transient UI (toasts, banners) without affecting layout. 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 or .bottom ). Avoid overlays that block all interaction unless explicitly needed. Don't stack many overlays; use a queue or replace the current toast. fullScreenCover: Use .fullScreenCover(item:) for immersive presentations that cover the entire screen (media viewers, onboarding flows). Common Mistakes Using non-lazy stacks for large collections -- causes all children to render immediately Placing GeometryReader inside lazy containers -- defeats lazy loading Using array indices as ForEach IDs -- causes incorrect diffing and UI bugs Nesting scroll views of the same axis -- causes gesture conflicts Heavy custom layouts inside List rows -- use ScrollView + LazyVStack instead Missing .contentShape(Rectangle()) on tappable rows -- tap area is text-only Hard-coding frame dimensions for sheets -- use .presentationSizing instead Running searches on empty strings -- always guard against empty queries Mixing List and ScrollView in the same hierarchy -- gesture conflicts 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