Technologies›SwiftUI›Scrolling

ScrollViewProxy struct

iOSmacOStvOSwatchOSvisionOSiOS 14.0+✓ renders

A proxy value that supports programmatic scrolling of the scrollable

How it works

A ScrollViewProxy is a lightweight handle that lets you drive a scroll view's content offset from code rather than waiting on the user to drag. SwiftUI hands you one inside a ScrollViewReader, and through it you ask the enclosing scroll view to bring a particular child into view by its identity. Reach for it whenever an event outside the scroll gesture — a button tap, a search result, a newly appended message — needs to move the viewport to a specific row.

  1. Obtain the proxy from ScrollViewReader

    You never construct a ScrollViewProxy yourself; you receive one as the argument to the ScrollViewReader content closure. Here it arrives as proxy in, and it stays valid for the lifetime of that reader, so any view inside the closure — including the Button that sits above the scroll view — can capture and use it.

  2. Call scrollTo(_:anchor:) to move the viewport

    The proxy's core member is scrollTo(_:anchor:), which takes the identity of a target child and scrolls until that child is visible. In the example proxy.scrollTo(50, anchor: .top) asks the scroll view to reposition so the view identified by 50 rests against the top edge.

  3. Give the anchor a UnitPoint

    The anchor parameter is a UnitPoint describing where the target should land within the visible region — .top, .center, .bottom, and so on. Passing .top pins row 50 to the top; omitting anchor (or passing nil) scrolls only far enough to make the target visible without forcing a precise alignment.

  4. Identify the scroll targets with id(_:)

    scrollTo can only find a child that carries a matching identity, so each scrollable view must be tagged with .id(_:). The ForEach rows attach .id(i), which is what lets the integer 50 passed to scrollTo resolve to the corresponding Text("Row \(i)").

  5. Animate the jump with withAnimation

    Scrolling through the proxy happens immediately by default. Wrapping the call in withAnimation { proxy.scrollTo(50, anchor: .top) } turns the jump into a smooth scroll, because the offset change becomes part of the surrounding transaction.

Try it — Change proxy.scrollTo(50, anchor: .top) to proxy.scrollTo(50, anchor: .center) and watch row 50 settle in the middle of the viewport instead of at its top edge.

Example & preview

Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.

ScrollViewProxy.swift
struct ScrollViewProxyDemo: View {
    var body: some View {
        ScrollViewReader { proxy in
            VStack(spacing: 12) {
                Button("Jump to Row 50") {
                    withAnimation {
                        proxy.scrollTo(50, anchor: .top)
                    }
                }
                .buttonStyle(.borderedProminent)

                ScrollView {
                    LazyVStack(spacing: 8) {
                        ForEach(0..<100, id: \.self) { i in
                            Text("Row \(i)")
                                .frame(maxWidth: .infinity)
                                .padding(8)
                                .background(Color.blue.opacity(0.1))
                                .id(i)
                        }
                    }
                }
            }
            .padding()
        }
    }
}
Live preview
Jump to Row 50 Row 0 Row 1 Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10 Row 11 Row 12 Row 13 Row 14 Row 15 Row 16 Row 17 Row 18 Row 19 Row 20 Row 21 Row 22 Row 23 Row 24 Row 25 Row 26 Row 27 Row 28 Row 29 Row 30 Row 31 Row 32 Row 33 Row 34 Row 35 Row 36 Row 37 Row 38 Row 39 Row 40 Row 41 Row 42 Row 43 Row 44 Row 45 Row 46 Row 47 Row 48 Row 49 Row 50 Row 51 Row 52 Row 53 Row 54 Row 55 Row 56 Row 57 Row 58 Row 59 Row 60 Row 61 Row 62 Row 63 Row 64 Row 65 Row 66 Row 67 Row 68 Row 69 Row 70 Row 71 Row 72 Row 73 Row 74 Row 75 Row 76 Row 77 Row 78 Row 79 Row 80 Row 81 Row 82 Row 83 Row 84 Row 85 Row 86 Row 87 Row 88 Row 89 Row 90 Row 91 Row 92 Row 93 Row 94 Row 95 Row 96 Row 97 Row 98 Row 99
Jump to Row 50 Row 0 Row 1 Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10 Row 11 Row 12 Row 13 Row 14 Row 15 Row 16 Row 17 Row 18 Row 19 Row 20 Row 21 Row 22 Row 23 Row 24 Row 25 Row 26 Row 27 Row 28 Row 29 Row 30 Row 31 Row 32 Row 33 Row 34 Row 35 Row 36 Row 37 Row 38 Row 39 Row 40 Row 41 Row 42 Row 43 Row 44 Row 45 Row 46 Row 47 Row 48 Row 49 Row 50 Row 51 Row 52 Row 53 Row 54 Row 55 Row 56 Row 57 Row 58 Row 59 Row 60 Row 61 Row 62 Row 63 Row 64 Row 65 Row 66 Row 67 Row 68 Row 69 Row 70 Row 71 Row 72 Row 73 Row 74 Row 75 Row 76 Row 77 Row 78 Row 79 Row 80 Row 81 Row 82 Row 83 Row 84 Row 85 Row 86 Row 87 Row 88 Row 89 Row 90 Row 91 Row 92 Row 93 Row 94 Row 95 Row 96 Row 97 Row 98 Row 99
swift → lexer → parser → sema → uiir → canvas Open in Studio ↗
What's new in SwiftUI 27 →