1# SwiftUI ScrollView Patterns Reference
2 
3## Table of Contents
4 
5- [ScrollViewReader for Programmatic Scrolling](#scrollviewreader-for-programmatic-scrolling)
6- [Scroll Position Tracking](#scroll-position-tracking)
7- [Scroll Transitions and Effects](#scroll-transitions-and-effects)
8- [Scroll Target Behavior](#scroll-target-behavior)
9- [Summary Checklist](#summary-checklist)
10 
11## ScrollViewReader for Programmatic Scrolling
12 
13**Use `ScrollViewReader` for scroll-to-top, scroll-to-bottom, and anchor-based jumps.**
14 
15```swift
16struct ChatView: View {
17    @State private var messages: [Message] = []
18    private let bottomID = "bottom"
19    
20    var body: some View {
21        ScrollViewReader { proxy in
22            ScrollView {
23                LazyVStack {
24                    ForEach(messages) { message in
25                        MessageRow(message: message)
26                            .id(message.id)
27                    }
28                    Color.clear
29                        .frame(height: 1)
30                        .id(bottomID)
31                }
32            }
33            .onChange(of: messages.count) { _, _ in
34                withAnimation {
35                    proxy.scrollTo(bottomID, anchor: .bottom)
36                }
37            }
38            .onAppear {
39                proxy.scrollTo(bottomID, anchor: .bottom)
40            }
41        }
42    }
43}
44```
45 
46### Scroll-to-Top Pattern
47 
48```swift
49struct FeedView: View {
50    @State private var items: [Item] = []
51    @State private var scrollToTop = false
52    private let topID = "top"
53    
54    var body: some View {
55        ScrollViewReader { proxy in
56            ScrollView {
57                LazyVStack {
58                    Color.clear
59                        .frame(height: 1)
60                        .id(topID)
61                    
62                    ForEach(items) { item in
63                        ItemRow(item: item)
64                    }
65                }
66            }
67            .onChange(of: scrollToTop) { _, shouldScroll in
68                if shouldScroll {
69                    withAnimation {
70                        proxy.scrollTo(topID, anchor: .top)
71                    }
72                    scrollToTop = false
73                }
74            }
75        }
76    }
77}
78```
79 
80**Why**: `ScrollViewReader` provides programmatic scroll control with stable anchors. Always use stable IDs and explicit animations.
81 
82## Scroll Position Tracking
83 
84### Basic Scroll Position
85 
86**Avoid** - Storing scroll position directly triggers view updates on every scroll frame:
87 
88```swift
89// ❌ Bad Practice - causes unnecessary re-renders
90struct ContentView: View {
91    @State private var scrollPosition: CGFloat = 0
92 
93    var body: some View {
94        ScrollView {
95            content
96                .background(
97                    GeometryReader { geometry in
98                        Color.clear
99                            .preference(
100                                key: ScrollOffsetPreferenceKey.self,
101                                value: geometry.frame(in: .named("scroll")).minY
102                            )
103                    }
104                )
105        }
106        .coordinateSpace(name: "scroll")
107        .onPreferenceChange(ScrollOffsetPreferenceKey.self) { value in
108            scrollPosition = value
109        }
110    }
111}
112```
113 
114**Preferred** - Check scroll position and update a flag based on thresholds for smoother, more efficient scrolling:
115 
116```swift
117// ✅ Good Practice - only updates state when crossing threshold
118struct ContentView: View {
119    @State private var startAnimation: Bool = false
120 
121    var body: some View {
122        ScrollView {
123            content
124                .background(
125                    GeometryReader { geometry in
126                        Color.clear
127                            .preference(
128                                key: ScrollOffsetPreferenceKey.self,
129                                value: geometry.frame(in: .named("scroll")).minY
130                            )
131                    }
132                )
133        }
134        .coordinateSpace(name: "scroll")
135        .onPreferenceChange(ScrollOffsetPreferenceKey.self) { value in
136            if value < -100 {
137                startAnimation = true
138            } else {
139                startAnimation = false
140            }
141        }
142    }
143}
144 
145struct ScrollOffsetPreferenceKey: PreferenceKey {
146    static var defaultValue: CGFloat = 0
147    static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
148        value = nextValue()
149    }
150}
151```
152 
153### Scroll-Based Header Visibility
154 
155```swift
156struct ContentView: View {
157    @State private var showHeader = true
158    
159    var body: some View {
160        VStack(spacing: 0) {
161            if showHeader {
162                HeaderView()
163                    .transition(.move(edge: .top))
164            }
165            
166            ScrollView {
167                content
168                    .background(
169                        GeometryReader { geometry in
170                            Color.clear
171                                .preference(
172                                    key: ScrollOffsetPreferenceKey.self,
173                                    value: geometry.frame(in: .named("scroll")).minY
174                                )
175                        }
176                    )
177            }
178            .coordinateSpace(name: "scroll")
179            .onPreferenceChange(ScrollOffsetPreferenceKey.self) { offset in
180                if offset < -50 { // Scrolling down
181                   withAnimation { showHeader = false }
182                } else if offset > 50 { // Scrolling up
183                  withAnimation { showHeader = true }
184                }
185            }
186        }
187    }
188}
189```
190 
191## Scroll Transitions and Effects
192 
193> **iOS 17+**: All APIs in this section require iOS 17 or later.
194 
195### Scroll-Based Opacity
196 
197```swift
198struct ParallaxView: View {
199    var body: some View {
200        ScrollView {
201            LazyVStack(spacing: 20) {
202                ForEach(items) { item in
203                    ItemCard(item: item)
204                        .visualEffect { content, geometry in
205                            let frame = geometry.frame(in: .scrollView)
206                            let distance = min(0, frame.minY)
207                            return content
208                                .opacity(1 + distance / 200)
209                        }
210                }
211            }
212        }
213    }
214}
215```
216 
217### Parallax Effect
218 
219```swift
220struct ParallaxHeader: View {
221    var body: some View {
222        ScrollView {
223            VStack(spacing: 0) {
224                Image("hero")
225                    .resizable()
226                    .aspectRatio(contentMode: .fill)
227                    .frame(height: 300)
228                    .visualEffect { content, geometry in
229                        let offset = geometry.frame(in: .scrollView).minY
230                        return content
231                            .offset(y: offset > 0 ? -offset * 0.5 : 0)
232                    }
233                    .clipped()
234                
235                ContentView()
236            }
237        }
238    }
239}
240```
241 
242## Scroll Target Behavior
243 
244> **iOS 17+**: All APIs in this section require iOS 17 or later.
245 
246### Paging ScrollView
247 
248```swift
249struct PagingView: View {
250    var body: some View {
251        ScrollView(.horizontal) {
252            LazyHStack(spacing: 0) {
253                ForEach(pages) { page in
254                    PageView(page: page)
255                        .containerRelativeFrame(.horizontal)
256                }
257            }
258            .scrollTargetLayout()
259        }
260        .scrollTargetBehavior(.paging)
261    }
262}
263```
264 
265### Snap to Items
266 
267```swift
268struct SnapScrollView: View {
269    var body: some View {
270        ScrollView(.horizontal) {
271            LazyHStack(spacing: 16) {
272                ForEach(items) { item in
273                    ItemCard(item: item)
274                        .frame(width: 280)
275                }
276            }
277            .scrollTargetLayout()
278        }
279        .scrollTargetBehavior(.viewAligned)
280        .contentMargins(.horizontal, 20)
281    }
282}
283```
284 
285## Summary Checklist
286 
287- [ ] Use `ScrollViewReader` with stable IDs for programmatic scrolling
288- [ ] Always use explicit animations with `scrollTo()`
289- [ ] Use `.visualEffect` for scroll-based visual changes
290- [ ] Use `.scrollTargetBehavior(.paging)` for paging behavior
291- [ ] Use `.scrollTargetBehavior(.viewAligned)` for snap-to-item behavior
292- [ ] Gate frequent scroll position updates by thresholds
293- [ ] Use preference keys for custom scroll position tracking
294