ScrollView

Component that wraps platform ScrollView while providing integration with touch locking “responder” system. ScrollView renders all its react child components at once, but this has a performance downside.

Import

import { ScrollView } from 'react-native';

Basic Usage

import React from 'react';
import { ScrollView, Text, StyleSheet } from 'react-native';

function BasicScrollView() {
  return (
    <ScrollView style={styles.container}>
      <Text style={styles.text}>Scroll me down</Text>
      {[...Array(20)].map((_, i) => (
        <Text key={i} style={styles.item}>Item {i}</Text>
      ))}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  text: {
    fontSize: 20,
    padding: 20,
  },
  item: {
    padding: 20,
    borderBottomWidth: 1,
    borderBottomColor: '#ccc',
  },
});

Props

Layout Props

ViewStyle

These styles will be applied to the scroll view content container which wraps all of the child views.

boolean

default:"false"

When true, the scroll view’s children are arranged horizontally in a row instead of vertically in a column.

ViewStyle

Styles to apply to the scroll view container.

Scrolling Behavior

boolean

default:"false"

When true, the scroll view stops on multiples of the scroll view’s size when scrolling. This can be used for horizontal pagination.

boolean

default:"true"

When false, the content does not scroll.

'fast' | 'normal' | number

default:"'normal'"

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger.

normal - 0.998 on iOS, 0.985 on Android
fast - 0.99 on iOS, 0.9 on Android

number

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view.

number[]

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children.

boolean

default:"true"

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set to false to disable this behavior.

boolean

default:"true"

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set to false to disable this behavior.

boolean

default:"false"

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is.

Content Offset

{x: number, y: number}

default:"{x: 0, y: 0}"

Used to manually set the starting scroll offset.

Keyboard Behavior

'none' | 'on-drag' | 'interactive'

default:"'none'"

Determines whether the keyboard gets dismissed in response to a drag.

none - Drags do not dismiss the keyboard
on-drag - The keyboard is dismissed when a drag begins
interactive - (iOS only) The keyboard is dismissed interactively with the drag

boolean | 'always' | 'never' | 'handled'

default:"'never'"

Determines when the keyboard should stay visible after a tap.

never - Tapping outside of the focused text input dismisses the keyboard
always - The keyboard will not dismiss automatically
handled - The keyboard will not dismiss automatically when the tap was handled by children

Scroll Indicators

boolean

default:"true"

When true, shows a horizontal scroll indicator.

boolean

default:"true"

When true, shows a vertical scroll indicator.

Performance

boolean

Experimental: When true, offscreen child views are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

Event Handlers

(event: ScrollEvent) => void

Fires at most once per frame during scrolling. The frequency can be controlled using the scrollEventThrottle prop.

(event: ScrollEvent) => void

Called when the user begins to drag the scroll view.

(event: ScrollEvent) => void

Called when the user stops dragging the scroll view and it either stops or begins to glide.

(event: ScrollEvent) => void

Called when the momentum scroll starts (scroll which occurs as the ScrollView glides to a stop).

(event: ScrollEvent) => void

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

(width: number, height: number) => void

Called when scrollable content view of the ScrollView changes.

number

This controls how often the scroll event will be fired while scrolling (in milliseconds). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems. The default value is zero, which results in the scroll event being sent only once per frame.

Identification Props

string

Used to locate this view in end-to-end tests.

Platform-Specific Props

iOS
Android

boolean

default:"true"

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction.

boolean

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. Default is true when horizontal={true} and false otherwise.

boolean

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. Default is false when horizontal={true} and true otherwise.

boolean

default:"true"

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar.

boolean

default:"false"

Controls whether the ScrollView should automatically adjust its contentInset and scrollViewInsets when the Keyboard changes its size.

boolean

default:"true"

Controls whether iOS should automatically adjust the scroll indicator insets. Available on iOS 13 and later.

Insets

default:"{top: 0, left: 0, bottom: 0, right: 0}"

The amount by which the scroll view content is inset from the edges of the scroll view.

'automatic' | 'scrollableAxes' | 'never' | 'always'

default:"'never'"

This property specifies how the safe area insets are used to modify the content area of the scroll view.

Insets

default:"{0, 0, 0, 0}"

The amount by which the scroll view indicators are inset from the edges of the scroll view.

boolean

default:"true"

When true, the scroll view scrolls to top when the status bar is tapped.

'default' | 'black' | 'white'

default:"'default'"

The style of the scroll indicators.

boolean

default:"false"

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging.

number

default:"1.0"

The maximum allowed zoom scale.

number

default:"1.0"

The minimum allowed zoom scale.

boolean

default:"true"

When true, ScrollView allows use of pinch gestures to zoom in and out.

Methods

method

Scrolls to a given x, y offset, either immediately or with a smooth animation.

scrollViewRef.scrollTo({ x: 0, y: 0, animated: true });

method

Scrolls to the end of the ScrollView.

scrollViewRef.scrollToEnd({ animated: true });

method

Displays the scroll indicators momentarily.

scrollViewRef.flashScrollIndicators();

Examples

Horizontal ScrollView

import { ScrollView, View, StyleSheet } from 'react-native';

function HorizontalScroll() {
  return (
    <ScrollView horizontal style={styles.container}>
      {[...Array(10)].map((_, i) => (
        <View key={i} style={styles.box} />
      ))}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  box: {
    width: 100,
    height: 100,
    backgroundColor: '#007AFF',
    margin: 10,
  },
});

ScrollView with Pagination

import { ScrollView, View, Dimensions, StyleSheet } from 'react-native';

const { width } = Dimensions.get('window');

function PaginatedScroll() {
  return (
    <ScrollView
      horizontal
      pagingEnabled
      showsHorizontalScrollIndicator={false}
      style={styles.container}
    >
      {[...Array(5)].map((_, i) => (
        <View key={i} style={[styles.page, { width }]} />
      ))}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  page: {
    height: 200,
    backgroundColor: '#007AFF',
  },
});

ScrollView with Ref

import { ScrollView, Button, View, StyleSheet } from 'react-native';
import { useRef } from 'react';

function ScrollViewWithRef() {
  const scrollViewRef = useRef(null);

  return (
    <View style={styles.container}>
      <Button
        title="Scroll to top"
        onPress={() => scrollViewRef.current?.scrollTo({ y: 0 })}
      />
      <ScrollView ref={scrollViewRef} style={styles.scrollView}>
        {[...Array(20)].map((_, i) => (
          <View key={i} style={styles.item} />
        ))}
      </ScrollView>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  scrollView: {
    flex: 1,
  },
  item: {
    height: 100,
    backgroundColor: '#f0f0f0',
    marginVertical: 10,
  },
});

Core Components

User Interface

List Components

Android Components

iOS Components

Import

Basic Usage

Props

Layout Props

Scrolling Behavior

Content Offset

Keyboard Behavior

Scroll Indicators

Performance

Event Handlers

Identification Props

Platform-Specific Props

Methods

Examples

Horizontal ScrollView

ScrollView with Ref

​Import

​Basic Usage

​Props

​Layout Props

​Scrolling Behavior

​Content Offset

​Keyboard Behavior

​Scroll Indicators

​Performance

​Event Handlers

​Identification Props

​Platform-Specific Props

​Methods

​Examples

​Horizontal ScrollView

​ScrollView with Pagination

​ScrollView with Ref

Import

Basic Usage

Props

Layout Props

Scrolling Behavior

Content Offset

Keyboard Behavior

Scroll Indicators

Performance

Event Handlers

Identification Props

Platform-Specific Props

Methods

Examples

Horizontal ScrollView

ScrollView with Pagination

ScrollView with Ref