ScrollPosition
A type that defines the semantic position of where a scroll view is scrolled within its content.
Declaration
type ScrollPosition =
| {}
| { edge: Edge; }
| { id: string | number | boolean; anchor?: UnitPoint | null; }
| { point: CGPoint; }
| { x: number; }
| { x: number; y: number; }
| { y: number; }
| ScrollPositionChain;struct ScrollPositionType methods
Overview
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.
From Apple’s SwiftUI documentation. Code samples there are Swift.
Used by
See also
More in Layout.
- AlignmentAn alignment in both axes.
- ContainerBackgroundPlacementThe placement of a container background.
- ContainerValuesReadableKeys of SwiftUI ContainerValues JavaScript can read.
- ContainerValuesWritableKeys of SwiftUI ContainerValues JavaScript can write.
- ControlSizeThe size classes, like regular or small, that you can apply to controls within a view.
- DocumentLaunchGeometryProxyA proxy for access to the frame of the scene and its title view.
- DynamicTypeSizeA Dynamic Type size, which specifies how large scalable content should be.
- EdgeAn enumeration to indicate one edge of a rectangle.
- EdgeInsetsThe inset distances for the sides of a rectangle.
- EdgeInsetsChainEdgeInsets with chained calls: SwiftUI.EdgeInsets.inset(...).
- EdgeSetAn efficient set of edges.
- GeometryProxyA proxy for access to the size and coordinate space (for anchor resolution) of the container view.