Scroll views#

The ScrollView component displays its content within a scrollable region. As the user performs scroll gestures, the visible portion of the content is updated accordingly. You can scroll vertically, horizontally, or in both directions using the axes prop.

Type#

1type ScrollViewProps = {
2  axes?: AxisSet
3  children?: VirtualNode | VirtualNode[] | (VirtualNode | undefined | null)[]
4}

Overview#

• Scroll direction is controlled by the axes property.
• Contents are placed inside children, typically using layouts like <VStack> or <HStack>.
• Zooming is not supported.

Default Behavior#

• The default scroll axis is vertical.
• Scroll indicators are shown based on platform conventions unless configured via modifiers.

Example#

1<ScrollView>
2  <VStack>
3    {new Array(100).fill('').map((_, index) => (
4      <Text>Row {index}</Text>
5    ))}
6  </VStack>
7</ScrollView>

ScrollView Modifiers#

You can apply the following view modifiers to configure scroll-related behavior.

scrollIndicator#

Controls the visibility of scroll indicators.

Type#

1scrollIndicator?: ScrollScrollIndicatorVisibility | {
2  visibility: ScrollScrollIndicatorVisibility
3  axes: AxisSet
4}

ScrollScrollIndicatorVisibility options:#

• "automatic": Follows platform default behavior.
• "visible": Indicators appear but may auto-hide based on OS behavior.
• "hidden": Hidden unless overridden by system behavior.
• "never": Never show indicators.

Example#

1<ScrollView scrollIndicator="never">
2  <VStack>{/* content */}</VStack>
3</ScrollView>

With axis-specific visibility:

1<ScrollView
2  scrollIndicator={{
3    visibility: "hidden",
4    axes: "vertical"
5  }}
6>
7  <VStack>{/* content */}</VStack>
8</ScrollView>

scrollDisabled#

Enables or disables scrolling behavior entirely.

Type#

1scrollDisabled?: boolean

Example#

1<ScrollView scrollDisabled>
2  <Text>This scroll view is locked.</Text>
3</ScrollView>

scrollClipDisabled#

Controls whether the scroll view clips content that extends beyond its bounds.

Type#

1scrollClipDisabled?: boolean

Example#

1<ScrollView scrollClipDisabled>
2  {/* Content may overflow scroll bounds visually */}
3</ScrollView>

scrollDismissesKeyboard#

Determines how the scroll interaction affects the software keyboard.

Type#

1scrollDismissesKeyboard?: ScrollDismissesKeyboardMode

Options#

• "automatic": Default behavior based on context.
• "immediately": Dismiss keyboard as soon as scrolling starts.
• "interactively": Allow user to drag to dismiss keyboard.
• "never": Scrolling will not dismiss the keyboard.

Example#

1<ScrollView scrollDismissesKeyboard="interactively">
2  {/* Content with text input */}
3</ScrollView>

defaultScrollAnchor#

Defines which point in the content should be visible initially or stay anchored when content size changes.

Type#

1defaultScrollAnchor?: KeywordPoint | Point

KeywordPoint values#

• "top", "bottom", "leading", "trailing", "center", "topLeading", "bottomTrailing" etc.

Example#

1<ScrollView defaultScrollAnchor="bottom">
2  <VStack>
3    {/* New content will appear anchored to the bottom */}
4  </VStack>
5</ScrollView>

AxisSet#

Defines the scrollable directions for a scroll view.

Type#

1type AxisSet = 'vertical' | 'horizontal' | 'all'

Usage#

1<ScrollView axes="horizontal">
2  <HStack>{/* horizontally scrollable content */}</HStack>
3</ScrollView>

scrollTargetLayout#

Applies this modifier to layout containers such as LazyHStack, LazyVStack, HStack, or VStack that represent the main repeating content inside a ScrollView.

Type#

1scrollTargetLayout?: boolean

Usage#

When set to true, this modifier designates the associated layout container as a scroll target region within the ScrollView. It allows the scroll behavior system to determine how scrolling should align to elements within the container.

1<ScrollView axes="horizontal">
2  <LazyHStack scrollTargetLayout>
3    {items.map(item => <Text>{item.title}</Text>)}
4  </LazyHStack>
5</ScrollView>

scrollTargetBehavior#

Defines how scrollable views behave when aligning content to scroll targets.

Type#

1scrollTargetBehavior?: ScrollTargetBehavior

1type ScrollTargetBehavior =
2  | "paging"
3  | "viewAligned"
4  | "viewAlignedLimitAutomatic"
5  | "viewAlignedLimitAlways"
6  | "viewAlignedLimitNever"
7  | "viewAlignedLimitAlwaysByFew"
8  | "viewAlignedLimitAlwaysByOne"

Description of Variants#

• "paging": Scrolls one page at a time, aligned to the container’s dimensions.
• "viewAligned": Scrolls to align views directly, based on view frames.
• "viewAlignedLimitAutomatic": Limits scrolling in compact horizontal size classes, but allows full scrolling otherwise.
• "viewAlignedLimitAlways": Always restricts scrolling to a limited number of items.
• "viewAlignedLimitNever": Allows unrestricted scrolling without view-based limitations.
• "viewAlignedLimitAlwaysByFew" (iOS 18.0+): Limits scrolling to a small number of views per gesture, automatically determined.
• "viewAlignedLimitAlwaysByOne" (iOS 18.0+): Restricts each scroll gesture to advance exactly one view at a time.

Description#

This modifier configures the scroll behavior, such as paging and alignment strategy, for views within a scrollable container.

scrollContentBackground#

Specifies the visibility of the background for scrollable views, such as ScrollView, within the current view context.

Type#

1scrollContentBackground?: Visibility

Description#

This modifier controls whether the default background behind scrollable content (typically a system-provided background) is shown, hidden, or determined automatically based on system behavior.

It is commonly used when customizing the appearance of scrollable views or when layering custom backgrounds behind scroll content.

Visibility Options#

• 'automatic' The system decides whether the background should be visible based on the current context and platform conventions.

• 'hidden' Hides the scroll view’s default background, allowing custom background layers or transparent effects.

• 'visible' Forces the default scroll content background to be shown, even if a custom background is present.

Example: Hiding Scroll Background#

1<List scrollContentBackground="hidden">
2  <Text>No background here</Text>
3</List>

This example removes the default background from the scroll view, making it fully transparent or allowing underlying views to show through.

Summary#