Skip to content

dpearson2699/swift-ios-skills / skills/swiftui-layout-components

swiftui-layout-components

Verified

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.

FileKindSize
SKILL.mdskill md11.5 KB
evals/evals.jsonconfig4.9 KB
references/form.mdmarkdown3.0 KB
references/grids.mdmarkdown6.5 KB
references/list.mdmarkdown3.7 KB
references/scrollview.mdmarkdown9.1 KB

references/scrollview.md

View on GitHub
# ScrollView and Lazy stacks

## Contents

- [Intent](#intent)
- [Core patterns](#core-patterns)
- [Example: vertical custom feed](#example-vertical-custom-feed)
- [ScrollPosition capabilities](#scrollposition-capabilities)
- [Paged primary and detail reveals](#paged-primary-and-detail-reveals)
- [Example: horizontal chips](#example-horizontal-chips)
- [Example: adaptive grid](#example-adaptive-grid)
- [Design choices to keep](#design-choices-to-keep)
- [iOS 26 Scroll Edge Effects](#ios-26-scroll-edge-effects)
- [Pitfalls](#pitfalls)

## Intent

Use `ScrollView` with `LazyVStack`, `LazyHStack`, or `LazyVGrid` when you need custom layout, mixed content, or horizontal/ grid-based scrolling.

## Core patterns

- Prefer `ScrollView` + `LazyVStack` for chat-like or custom feed layouts.
- Use `ScrollView(.horizontal)` + `LazyHStack` for chips, tags, avatars, and media strips.
- Use `LazyVGrid` for icon/media grids; prefer adaptive columns when possible.
- Use `ScrollPosition` for programmatic scrolling: scroll-to-id, scroll-to-edge, and point-based offsets.
- Use `safeAreaInset(edge:)` for input bars that should stick above the keyboard.

## Example: vertical custom feed

```swift
@MainActor
struct ConversationView: View {
  @State private var scrollPosition = ScrollPosition(edge: .bottom)

  var body: some View {
    ScrollView {
      LazyVStack {
        ForEach(messages) { message in
          MessageRow(message: message)
        }
      }
      .scrollTargetLayout()
      .padding(.horizontal, .layoutPadding)
    }
    .scrollPosition($scrollPosition)
    .safeAreaInset(edge: .bottom) {
      MessageInputBar()
    }
    .onChange(of: messages.last?.id) {
      withAnimation { scrollPosition.scrollTo(edge: .bottom) }
    }
  }
}
```

## ScrollPosition capabilities

`ScrollPosition` (iOS 18+) replaces `ScrollViewReader` for programmatic scrolling. It is declarative, supports bidirectional position tracking, and does not require a closure wrapper.

**Setup:** Declare state and attach to the scroll view. Apply `.scrollTargetLayout()` to the inner layout container so SwiftUI can track individual view identities.

```swift
@State private var scrollPosition = ScrollPosition(idType: Message.ID.self)

ScrollView {
    LazyVStack {
        ForEach(messages) { message in
            MessageRow(message: message)
        }
    }
    .scrollTargetLayout()
}
.scrollPosition($scrollPosition)
```

**Scroll to a specific item:**

```swift
scrollPosition.scrollTo(id: message.id, anchor: .top)
```

**Scroll to an edge:**

```swift
scrollPosition.scrollTo(edge: .bottom)
```

**Read the current position:**

```swift
if let currentID = scrollPosition.viewID(type: Message.ID.self) {
    // The view with this ID is currently at the scroll anchor
}
```

**Detect user-initiated scrolls:**

```swift
.onChange(of: scrollPosition.isPositionedByUser) { _, byUser in
    if byUser {
        // User scrolled manually -- show "scroll to bottom" button
    }
}
```

## Paged primary and detail reveals

For a primary surface that pages into secondary details, let the scroll view remain the interaction source of truth. Use `ScrollPosition` for semantic or programmatic positioning, then derive one normalized progress value from scroll offset for continuous presentation.

```swift
private enum RevealPage: Hashable {
    case primary
    case details
}

@MainActor
struct RevealPager: View {
    @State private var position = ScrollPosition(idType: RevealPage.self)
    @State private var progress: CGFloat = 0
    @State private var isZooming = false
    @State private var isCropping = false

    var body: some View {
        ScrollView(.vertical) {
            LazyVStack(spacing: 0) {
                PrimarySurface(progress: progress)
                    .containerRelativeFrame(.vertical)
                    .id(RevealPage.primary)

                DetailSurface(progress: progress)
                    .containerRelativeFrame(.vertical)
                    .id(RevealPage.details)
            }
            .scrollTargetLayout()
        }
        .scrollPosition($position)
        .scrollTargetBehavior(.paging)
        .onScrollGeometryChange(for: CGFloat.self) { geometry in
            let revealDistance = max(geometry.containerSize.height, 1)
            let offset = geometry.visibleRect.minY
            return min(max(offset / revealDistance, 0), 1)
        } action: { _, newProgress in
            progress = newProgress
        }
        .scrollDisabled(isZooming || isCropping)
    }
}
```

Use the same `progress` to derive opacity, offset, scale, blur, toolbar treatment, and reveal affordances. Keep these calculations in `RevealPager`'s small presentation subtree; do not publish pixel-by-pixel offsets into a shared store or invalidate an entire screen.

Avoid parallel state such as `isDetailsVisible`, `isToolbarVisible`, and a separate drag gesture that all describe the same transition. Derive thresholds from `progress` when a Boolean presentation choice is needed. Retain separate state only for a genuinely discrete event or interaction.

`onScrollGeometryChange` runs as the geometry changes frequently. Transform `ScrollGeometry` into the smallest useful `Equatable` value. A scalar is appropriate for smooth progress; use a threshold `Bool` or quantized value when per-pixel precision is unnecessary.

Use `onScrollVisibilityChange` or `onScrollTargetVisibilityChange` for discrete threshold-crossing effects such as deduplicated haptics, analytics, media activation, or accessibility announcements. Do not use visibility callbacks as continuous animation progress. A visibility threshold does not guarantee that paging has settled; when an effect must wait for rest, gate the discrete visibility result with an idle `onScrollPhaseChange`.

Disable scrolling while a conflicting interaction owns the same gesture, such as zoom, crop, or precision editing. Remember that `.scrollDisabled` propagates through the environment to nested scrollable views.

Prevent feedback loops: presentation derived from `progress` must not change the page height, content inset, or other geometry used to calculate that progress. Prefer render-only effects such as opacity, offset, scale, and blur; isolate unavoidable layout changes from the measured scroll content.

> **Docs:** [ScrollPosition](https://sosumi.ai/documentation/swiftui/scrollposition) · [onScrollGeometryChange](https://sosumi.ai/documentation/swiftui/view/onscrollgeometrychange(for:of:action:)) · [onScrollVisibilityChange](https://sosumi.ai/documentation/swiftui/view/onscrollvisibilitychange(threshold:_:)) · [scrollDisabled](https://sosumi.ai/documentation/swiftui/view/scrolldisabled(_:))

## Example: horizontal chips

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

## Example: adaptive grid

```swift
let columns = [GridItem(.adaptive(minimum: 120))]

ScrollView {
  LazyVGrid(columns: columns) {
    ForEach(items) { item in
      GridItemView(item: item)
    }
  }
  .padding()
}
```

## Design choices to keep

- Use `Lazy*` stacks when item counts are large or unknown.
- Use non-lazy stacks for small, fixed-size content to avoid lazy overhead.
- Keep IDs stable for `ScrollPosition` tracking; changing IDs causes position jumps.
- Prefer explicit animations (`withAnimation`) when scrolling to an ID.

## iOS 26 Scroll Edge Effects

### scrollEdgeEffectStyle

Configure the visual treatment at scroll view edges (iOS 26+):

```swift
ScrollView {
    content
}
.scrollEdgeEffectStyle(.soft, for: .top)   // Soft fading edge at top
.scrollEdgeEffectStyle(.hard, for: .bottom) // Hard cutoff at bottom
```

`ScrollEdgeEffectStyle` values:
- `.automatic` -- platform default
- `.soft` -- soft fading edge effect
- `.hard` -- hard cutoff with dividing line

Use `scrollEdgeEffectHidden(_:for:)` to hide the edge effect entirely.

### backgroundExtensionEffect

Duplicates, mirrors, and blurs the view to extend behind safe area edges (iOS 26+):

```swift
NavigationSplitView {
    sidebar
} detail: {
    BannerView()
        .backgroundExtensionEffect()
}
```

Use sparingly -- Apple recommends only a single instance for visual clarity and performance. The modifier clips the view to prevent mirror overlap.

### safeAreaBar

Attach a bar view to the safe area edge, integrating with scroll edge effects (iOS 26+):

```swift
content
    .safeAreaBar(edge: .top) {
        FilterBar()
    }
```

## Pitfalls

- Avoid nesting scroll views of the same axis; it causes gesture conflicts.
- Don’t combine `List` and `ScrollView` in the same hierarchy without a clear reason.
- Overuse of `LazyVStack` for tiny content can add unnecessary complexity.
- Apply `scrollEdgeEffectStyle` on the ScrollView, not on inner content.
- Use `backgroundExtensionEffect()` on only one view per screen.
- Do not mirror one reveal transition into multiple booleans or a parallel drag state machine.
- Do not write raw per-frame scroll geometry into broad app state.
- Do not let progress-driven layout change the geometry used to calculate progress.
- Use visibility callbacks for discrete threshold effects, not continuous interpolation or an assumed settled state.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall