Components

ScrollView

ScrollView is a scrollable view that allows users to scroll through content that exceeds the visible area. ScrollView supports both vertical and horizontal scrolling.

Examples

Basic Usage

Preview unavailable for this example in the static docs build.

Show code

<ScrollView style={{ height: '200px' }}>
      <VStack spacing={10}>
        {Array.from({ length: 20 }, (_, i) => (
          <Text key={i}>Item {i + 1}</Text>
        ))}
      </VStack>
    </ScrollView>

Vertical Scrolling

Preview unavailable for this example in the static docs build.

Show code

<ScrollView direction="vertical" style={{ height: '200px' }}>
      <VStack spacing={10}>
        {Array.from({ length: 30 }, (_, i) => (
          <Text key={i}>Vertical Item {i + 1}</Text>
        ))}
      </VStack>
    </ScrollView>

Horizontal Scrolling

Preview unavailable for this example in the static docs build.

Show code

<ScrollView direction="horizontal" style={{ width: '100%', height: '100px' }}>
      <HStack spacing={10}>
        {Array.from({ length: 20 }, (_, i) => (
          <Text key={i} style={{ whiteSpace: 'nowrap' }}>Item {i + 1}</Text>
        ))}
      </HStack>
    </ScrollView>

Scroll Indicators

Preview unavailable for this example in the static docs build.

Show code

<ScrollView showsIndicators={false} style={{ height: '200px' }}>
      <VStack spacing={10}>
        {Array.from({ length: 20 }, (_, i) => (
          <Text key={i}>Item {i + 1} (no scrollbar)</Text>
        ))}
      </VStack>
    </ScrollView>

With Spacer

Preview unavailable for this example in the static docs build.

Show code

<ScrollView style={{ height: '200px' }}>
      <VStack spacing={10}>
        <Text>Top</Text>
        <Spacer />
        {Array.from({ length: 10 }, (_, i) => (
          <Text key={i}>Item {i + 1}</Text>
        ))}
        <Spacer />
        <Text>Bottom</Text>
      </VStack>
    </ScrollView>

Long Content

Preview unavailable for this example in the static docs build.

Show code

<ScrollView style={{ height: '300px' }}>
      <VStack spacing={15}>
        {Array.from({ length: 50 }, (_, i) => (
          <Text key={i}>Long content item {i + 1}</Text>
        ))}
      </VStack>
    </ScrollView>

Custom Styling

Preview unavailable for this example in the static docs build.

Show code

<ScrollView 
      style={{ 
        height: '200px', 
        border: '1px solid #ccc',
        borderRadius: '8px',
        padding: '10px'
      }}
    >
      <VStack spacing={10}>
        {Array.from({ length: 15 }, (_, i) => (
          <Text key={i}>Styled Item {i + 1}</Text>
        ))}
      </VStack>
    </ScrollView>

Programmatic Position

Preview unavailable for this example in the static docs build.

Show code

function ProgrammaticPositionDemo() {
  const [scrollPosition, setScrollPosition] = useState<IScrollPosition>()

  return (
    <VStack spacing={12}>
      <HStack spacing={8}>
        <Button onClick={() => setScrollPosition({ target: 'top' })}>Scroll to top</Button>
        <Button onClick={() => setScrollPosition({ target: 'middle' })}>Scroll to middle</Button>
        <Button onClick={() => setScrollPosition({ target: 'bottom' })}>Scroll to bottom</Button>
      </HStack>
      <ScrollView scrollPosition={scrollPosition} style={{ height: '220px' }}>
        <VStack spacing={12}>
          <ScrollTarget scrollId="top">
            <Text>Top anchor</Text>
          </ScrollTarget>
          {Array.from({ length: 12 }, (_, i) => (
            <Text key={i}>Scrollable item {i + 1}</Text>
          ))}
          <ScrollTarget scrollId="middle">
            <Text>Middle anchor</Text>
          </ScrollTarget>
          {Array.from({ length: 12 }, (_, i) => (
            <Text key={`tail-${i}`}>Tail item {i + 1}</Text>
          ))}
          <ScrollTarget scrollId="bottom">
            <Text>Bottom anchor</Text>
          </ScrollTarget>
        </VStack>
      </ScrollView>
    </VStack>
  )
}

API

Prop	Type	Required	Description
`direction`	`'horizontal' \| 'vertical'`	No	The scrollable axis of the scroll view. Default: `'vertical'`
`showsIndicators`	`boolean`	No	A Boolean value that indicates whether the scroll view displays the scroll indicators. Default: `true`
`scrollPosition`	`IScrollPosition`	No	The current scroll position of the view.
`onScrollPositionChange`	`(position: IScrollPosition) => void`	No	Called when the scroll position changes.
`onScrollPhaseChange`	`(phase: IScrollPhase) => void`	No	Called when the scroll interaction phase changes.

Inherits additional props from IBaseComponent.

Overview

ScrollView is a scrollable view that allows users to scroll through content that exceeds the visible area. ScrollView supports both vertical and horizontal scrolling.

SwiftUI Correspondence: Similar to SwiftUI's ScrollView.

Scroll Indicators

Hide scroll indicators if needed:

With Spacer

Use Spacer within ScrollView for flexible layouts:

Long Content

ScrollView handles long content efficiently:

Custom Styling

Apply custom styles to ScrollView:

Programmatic Position

Drive a scroll view from state and scroll to anchors with scrollPosition:

Notes

ScrollView requires explicit dimensions (height for vertical, width for horizontal)
Default scroll direction is vertical
Scroll indicators can be hidden with showsIndicators={false}
ScrollView supports all standard React children
Use ScrollView for content that may exceed container bounds
Use scrollPosition to keep scroll location in React state or jump to a ScrollTarget
Use onScrollPhaseChange to react to active scrolling versus idle states

Best Practices

Dimensions: Always provide explicit dimensions for ScrollView containers
Performance: For long lists, consider using LazyVStack or LazyHStack instead
Nested scrolling: Avoid nested ScrollViews in the same direction
Accessibility: Ensure scrollable content is accessible via keyboard navigation
Mobile: Test scrolling behavior on touch devices

ScrollTransition

ScrollTransition adapts SwiftUI's `scrollTransition` modifier into an explicit wrapper for web layouts.

ScrollViewReader

ScrollViewReader exposes a proxy that can scroll to child `ScrollTarget` anchors by identifier.

ScrollView

Examples

API

On this page