How it works
PagingScrollTargetBehavior is a scroll target behavior that snaps a scroll view's resting position to page boundaries, so each gesture settles on a whole page rather than coming to rest at an arbitrary offset. Reach for it when you want a paged, carousel-like feel — full-screen onboarding pages, image galleries, or horizontally swiped cards — where the content advances one container-sized page at a time. It replaces the manual offset math and gesture tracking you would otherwise need to recreate UIScrollView-style paging, expressing the intent declaratively through the scroll view's modifier chain.
Apply the behavior with scrollTargetBehavior(.paging)
The behavior is attached to the scroll view itself through the
scrollTargetBehavior(_:)modifier, which takes aScrollTargetBehaviorvalue. The.pagingshorthand resolves to aPagingScrollTargetBehaviorinstance, so writing.scrollTargetBehavior(.paging)is all it takes to switch the container from free scrolling to page-aligned snapping.Mark the snap targets with scrollTargetLayout()
Paging needs to know which subviews are candidate landing points. Calling
scrollTargetLayout()on the scrollable stack — here theHStackof cards — promotes its direct children into scroll targets, andPagingScrollTargetBehavioraligns the rest position to the page that encloses those targets. Without this layout, the behavior has no targets to page between.Page within a scroll axis
PagingScrollTargetBehaviorderives a page from the scroll view's container size along its scrolling axis. Because theScrollView(.horizontal)here scrolls sideways, each page spans the visible width, and a swipe advances by exactly one screenful — thewidth: 220of an individualRoundedRectangledoes not define the page; the container does.Construct it directly when you need the type
Although
.pagingis the idiomatic spelling,PagingScrollTargetBehavioris a publicstructyou can name explicitly —.scrollTargetBehavior(PagingScrollTargetBehavior())is equivalent. Spelling out the type is useful when assigning the behavior to a variable or returning it from a helper that vends a configured behavior.
.scrollTargetBehavior(.paging) to .scrollTargetBehavior(.viewAligned) and watch the scroll view settle on whichever card is nearest rather than snapping a full page at a time.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.
struct PagingScrollTargetBehaviorDemo: View {
let colors: [Color] = [.red, .green, .blue, .orange]
var body: some View {
ScrollView(.horizontal) {
HStack(spacing: 16) {
ForEach(0..<colors.count, id: \.self) { i in
RoundedRectangle(cornerRadius: 16)
.fill(colors[i])
.frame(width: 220, height: 280)
.overlay(Text("Page \(i + 1)").font(.title).bold().foregroundStyle(.white))
}
}
.scrollTargetLayout()
}
.scrollTargetBehavior(.paging)
.padding()
}
}