跳转至
Structure

ScrollView

A view that scrolls.

Declaration

struct ScrollView<Content> : View where Content : View

Overview

A view that allows the scrolling of its contained views.

Making a view scrollable

ScrollView is a container view that makes its content scrollable. For example:

struct ExampleView: View {
    var body: some View {
        ScrollView {
            VStack {
                Text("Bananas 🍌🍌")
                Text("Apples 🍏🍏")
                Text("Peaches 🍑🍑")
            }
        }
    }
}
A gif that displays a scroll view with a VStack containing three text elements being scrolled up and down.

In this example, the VStack containing the text is made scrollable by wrapping it in a ScrollView.

Note:

  • The content of a ScrollView is scrollable regardless of whether all of it fits on screen or not.
  • It is not possible to selectively disable the scrolling of a ScrollView, while allowing its content to remain interactive. A disabled(_:) attached to a ScrollView will disable both the scrolling and all the interaction with the content visible.
  • A ScrollView's scrollable region is sized to fit the content view passed to the ScrollView.
  • ScrollView fits to occupy as much space as possible. It is important to distinguish between the actual bounds of the scroll view, and the bounds of the content of the ScrollView.

Setting the direction of scrolling

The default scrolling direction of a ScrollView is vertical. ScrollView supports 3 types of scrolling:

  • vertical
  • horizontal
  • both vertical and horizontal

To set a single allowed direction for a ScrollView, specify the axis of direction in the initializer. For example:

struct ExampleView: View {
    var body: some View {
        ScrollView(.horizontal) {
            VStack {
                Text("Bananas 🍌🍌")
                Text("Apples 🍏🍏")
                Text("Peaches 🍑🍑")
            }
        }
    }
}
A gif that displays a .horizontal scroll view with a VStack containing three text elements being scrolled left and right.

This example takes the previous example, and modifies it so that the ScrollView scrolls horizontally. This ScrollView will not scroll vertically, as an explict axis, .horizontal, has been specified.

To allow both directions of scrolling, pass the set of axes that you want to permit. For example:

struct ExampleView: View {
    var body: some View {
        ScrollView([.horizontal, .vertical]) {
            VStack {
                Text("Bananas 🍌🍌")
                Text("Apples 🍏🍏")
                Text("Peaches 🍑🍑")
            }
        }
    }
}
A gif that displays a .horizontal and .vertical scroll view with a VStack containing three text elements being scrolled diagonally.

In this example, ScrollView can scroll both horizontally and vertically, because both axes have been specified explicitly.

Hiding the scroll view indicator

By default, a ScrollView's scroll indicator is visible upon user interaction.

Pass false to showsIndicators in init(_:showsIndicators:content:) to hide the scroll indicator(s). For example:

struct ExampleView: View {
    var body: some View {
        ScrollView(.horizontal, showsIndicators: false) {
            VStack {
                Text("Bananas 🍌🍌")
                Text("Apples 🍏🍏")
                Text("Peaches 🍑🍑")
            }
        }
    }
}
ScrollView Example 4

This ScrollView will never show a scroll indicator.

You do not need to specify an axis to use showsIndicators. For example:

struct ExampleView: View {
    var body: some View {
        ScrollView(showsIndicators: false) {
            VStack {
                Text("Bananas 🍌🍌")
                Text("Apples 🍏🍏")
                Text("Peaches 🍑🍑")
            }
        }
    }
}
A gif that displays a .horizontal scroll view with a VStack containing three text elements being scrolled left and right wihtout a visible scroll indicator.

This ScrollView hides its scroll indicator, with a default .vertical scroll direction.

Scrolling to an item

To programmatically scroll to a particular item in your ScrollView, use scrollTo(_:anchor:). ScrollViewProxy is a type that allows you to control a ScrollView, and can be obtained using a ScrollViewReader.

For example:

struct ExampleView: View {
    var body: some View {
        ScrollView {
            ScrollViewReader { (proxy: ScrollViewProxy) in
                Button("Jump to #32") {
                    proxy.scrollTo(32)
                }

                ForEach(1..<101) { number in
                    Text("Item #\(number)")
                        .id(number)
                }
            }
        }
    }
}
A gif that displays a scroll view with a VStack containing a button reading "Jump to # 32" directly above text elements reading "Item #_", where _ is filled by the numbers 1-101; when the button is clicked, the view jumps down to the location in the scroll where the text "Item #32" is at the bottom edge of the screen.

In this example, clicking the button reading "Jump to #32", will cause the ScrollView to scroll to the item with the ID of the value 32. To assign an ID to a view, use id(_:) as is done inside the ForEach, for each element.

The call of proxy.scrollTo(32) causes the ScrollView to scroll to the text reading "Item #32", with that text centered vertically in the ScrollView's bounds. To change the anchor of the finalled scrolled-to destination, specify an anchor via scrollTo(_:anchor:). For example:

struct ExampleView: View {
    var body: some View {
        ScrollView {
            ScrollViewReader { (proxy: ScrollViewProxy) in
                Button("Jump to #32") {
                    proxy.scrollTo(32, anchor: .top)
                }

                ForEach(1..<101) { number in
                    Text("Item #\(number)")
                        .id(number)
                }
            }
        }
    }
}
A gif that displays a scroll view with a VStack containing a button reading "Jump to # 32" directly above text elements reading "Item #_", where _ is filled by the numbers 1-101; when the button is clicked, the view jumps down to the location in the scroll where the text "Item #32" is at the top edge of the screen, as defined by anchor.

In this example, the ScrollView still scrolls to "Item #32", but this Text is seen at the top of the ScrollView, rather than it's vertical center. The anchor parameter uses a type, UnitPoint, to determine the relative alignment (relative to the scroll view's bounds) of the scrolled-to item.

Add a transition to your scrollTo(_:anchor:) with withAnimation(_:_:). For example:

struct ExampleView: View {
    var body: some View {
        ScrollView {
            ScrollViewReader { (proxy: ScrollViewProxy) in
                Button("Jump to #32") {
                    withAnimation(.easeInOut(duration: 60)) {
                        proxy.scrollTo(32, anchor: .top)
                    }
                }

                ForEach(1..<101) { number in
                    Text("Item #\(number)")
                        .id(number)
                }
            }
        }
    }
}
A gif that displays a scroll view with a VStack containing a button reading "Jump to # 32" directly above text elements reading "Item #_", where _ is filled by the numbers 1-101; when the button is clicked, the view jumps down to the location in the scroll where the text "Item #32" is at the top edge of the screen, as defined by the anchor.

Availability

iOS 13.0+

macOS 10.15+

tvOS 13.0+

watchOS 6.0+

Topics


Instance Property

axes The scrollable axes of the scroll view.

body The content and behavior of the scroll view.

content The scroll view's content.

showsIndicators A value that indicates whether the scroll view displays the scrollable component of the content offset, in a way that's suitable for the platform.


Initializer

init(_:showsIndicators:content:) Creates a new instance that's scrollable in the direction of the given axis and can show indicators while scrolling.


Type Alias

Body The type of view representing the body of this view.