ScrollPosition

struct · iOS 18.0+ · SDK 27.1

struct ScrollPosition

A type that defines the semantic position of where a scroll view is scrolled within its content. Use this type along with the ``View/scrollPosition(_:anchor:)`` modifier to control where a scroll view is positioned. You can use this type to scroll in a variety of ways: - scroll to a view with a provided identity - scroll to a concrete offset - scroll to an edge You can create a scroll position with a specified view identity type @State private var position = ScrollPosition(idType: MyItem.ID.self) SwiftUI will use that along with the views in the scroll view's scroll target layout to programmatically scroll to those views and to update the ``ScrollPosition/viewID`` property as the user scrolls. Use the ``View/scrollTargetLayout(isEnabled:)`` modifier to configure which layout contains your scroll targets. When scrolling to a view with an identifier, SwiftUI will update the position with the value of the top-most view scrolled within the visible region of the scroll view. In the following example, the position binding will update to reflect the top-most ItemView as the scroll view scrolls. @Binding var items: [MyItem] @State private var position: ScrollPosition = .init(idType: MyItem.ID.self) ScrollView { LazyVStack { ForEach(items) { item in ItemView(item) } } .scrollTargetLayout() } .scrollPosition($position) You can then query the currently scrolled id by using the ``ScrollPosition/viewID(type:)``. let viewID: MyItem.ID = position.viewID(type: MyItem.ID.self) While most use cases will use view identity based scrolling, you can also use the scroll position type to scroll to offsets or edges. For example, you can create a button that scrolls to the bottom of the scroll view by specifying an edge. Button("Scroll to bottom") { position.scrollTo(edge: .bottom) } When configuring a scroll position, SwiftUI will attempt to keep that position stable. For an edge, that means keeping a top aligned scroll view scrolled to the top if the content size changes. For a point, SwiftUI won't attempt to keep that exact offset scrolled when the content size changes nor will it update to a new offset when that changes. For view identity positions, SwiftUI will attempt to keep the view with the identity specified in the provided binding visible when events occur that might cause it to be scrolled out of view by the system. Some examples of these include: - The data backing the content of a scroll view is re-ordered. - The size of the scroll view changes, like when a window is resized on macOS or during a rotation on iOS. - The scroll view initially lays out it content defaulting to the top most view, but the binding has a different view's identity. You can provide an anchor to a view identity based position to: - Influence which view the system chooses as the view whose identity value will update the providing binding as the scroll view scrolls. - Control the alignment of the view when scrolling to a view when writing a new binding value. In the example below, the bottom most view will be chosen to update the position binding with. ScrollView { LazyVStack { ForEach(items) { item in ItemView(item) } } .scrollTargetLayout() } .scrollPosition($position, anchor: .bottom) For example, providing a value of ``UnitPoint/bottom`` will prefer to have the bottom-most view chosen and prefer to scroll to views aligned to the bottom. If no anchor has been provided, SwiftUI will scroll the minimal amount when using the scroll position to programmatically scroll to a view.

Members (21)

get isPositionedByUser(): boolean

var isPositionedByUser: Bool { get set }

set isPositionedByUser(value: boolean)

var isPositionedByUser: Bool { get set }

get x(): (number) | null

var x: CGFloat? { get }

get y(): (number) | null

var y: CGFloat? { get }

static initIdAnchor(id: (SDKHandle) & (SDKHandle), anchor?: (UnitPoint) | null): ScrollPosition

init(id: some Hashable & Sendable, anchor: UnitPoint? = nil)

get edge(): (Edge) | null

var edge: Edge? { get }

get point(): ({ x: number; y: number }) | null

var point: CGPoint? { get }

static initXY(x: number, y: number): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self, x: CGFloat, y: CGFloat)

static initX(x: number): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self, x: CGFloat)

static initY(y: number): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self, y: CGFloat)

static initEdge(edge: Edge): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self, edge: Edge)

static initPoint(point: { x: number; y: number }): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self, point: CGPoint)

static init(): ScrollPosition

init(idType: (some Hashable & Sendable).Type = Never.self)

viewIDType(type: "Bool" | "Int" | "UInt" | "Double" | "Float" | "String" | "CGFloat" | "Date" | "URL" | "Data" | "UUID"): (unknown) | null

func viewID<T>(type: T.Type) -> T? where T : Hashable, T : Sendable

get viewID(): ((SDKHandle) & (SDKHandle)) | null

var viewID: (any Hashable & Sendable)? { get }

scrollToXY(x: number, y: number): void

mutating func scrollTo(x: CGFloat, y: CGFloat)

scrollToX(x: number): void

mutating func scrollTo(x: CGFloat)

scrollToY(y: number): void

mutating func scrollTo(y: CGFloat)

scrollToIdAnchor(id: (SDKHandle) & (SDKHandle), anchor?: (UnitPoint) | null): void

mutating func scrollTo(id: some Hashable & Sendable, anchor: UnitPoint? = nil)

scrollToEdge(edge: Edge): void

mutating func scrollTo(edge: Edge)

scrollToPoint(point: { x: number; y: number }): void

mutating func scrollTo(point: CGPoint)

All SwiftUICore types →