react-native-scroll-into-view

Scroll a ReactNative View ref into the visible portion of a ScrollView.

Similar to DOMElement.scrollIntoView() for web, with some extras.

yarn add react-native-scroll-into-view
// or
npm install react-native-scroll-into-view --save

There is no native code: this library is compatible with Expo managed workflow.

---

Sponsor

ThisWeekInReact.com: the best newsletter to stay up-to-date with the React ecosystem:

---

Why ?

On long scrollable forms, can ensure errors become visible to the user on submit:

Building some kind of "sections index":

But really you are free to build whatever you want with it

Features:

• Declarative component API
• Imperative hook API
• Configurable at many levels
• Different alignment modes
• Insets
• Typescript definitions
• Support for composition/refs/other ScrollView wrappers (Animated.ScrollView, react-native-keyboard-aware-scroll-view, glamorous-native...)

Note we don't plan to support anything else than ScrollView. Virtualized lists generally offer methods to scroll to a given index.

Minimal hooks example

1import { View, Text, ScrollView } from 'react-native';
2import {
3  wrapScrollView,
4  useScrollIntoView,
5} from 'react-native-scroll-into-view';
6
7const CustomScrollView = wrapScrollView(ScrollView);
8
9function MyScreen() {
10  return (
11    <CustomScrollView>
12      <MyScreenContent />
13    </CustomScrollView>
14  );
15}
16
17function MyScreenContent() {
18  const scrollIntoView = useScrollIntoView();
19  const viewRef = useRef();
20  return (
21    <>
22      <Button onPress={() => scrollIntoView(viewRef.current)}>
23        Scroll a view ref into view
24      </Button>
25      // in android if the scroll is not working then add renderToHardwareTextureAndroid this to view
26      <View style={{ height: 100000 }}>
27        <Text>Some long ScrollView content</Text>
28      </View>
29
30      <View ref={viewRef}>
31        <Text>Will be scrolled into view on button press</Text>
32      </View>
33    </>
34  );
35}

API

1import {
2  ScrollIntoView, // enhanced View container
3  wrapScrollView, // simple wrapper, no config
4  wrapScrollViewConfigured, // complex wrapper, takes a config
5  useScrollIntoView, // access hook for imperative usage
6} from 'react-native-scroll-into-view';
7
8// Available options with their default value
9const options = {
10  // auto: ensure element appears fully inside the view (if not already inside). It may align to top or bottom.
11  // top: align element to top
12  // bottom: align element to bottom
13  // center: align element at the center of the view
14  align: 'auto',
15
16  // Animate the scrollIntoView() operation
17  animated: true,
18
19  // By default, scrollIntoView() calls are throttled a bit because it does not make much sense
20  // to scrollIntoView() 2 elements at the same time (and sometimes even impossible)
21  immediate: false,
22
23  // Permit to add top/bottom insets so that element scrolled into view
24  // is not touching directly the borders of the scrollview (like a padding)
25  insets: {
26    top: 0,
27    bottom: 0,
28  },
29
30  // Advanced: use these options as escape hatches if the lib default functions do not satisfy your needs
31  computeScrollY: (scrollViewLayout, viewLayout, scrollY, insets, align) => {},
32  measureElement: viewRef => {},
33};
34
35// Wrap the original ScrollView
36const CustomScrollView = wrapScrollView(ScrollView);
37
38// Use the wrapped CustomScrollView as a replacement of ScrollView
39function MyScreen() {
40  return (
41    <CustomScrollView
42      // Can provide default options (overrideable)
43      scrollIntoViewOptions={scrollIntoViewOptions}
44    >
45      <ScreenContent />
46    </CustomScrollView>
47  );
48}
49
50// Implement ScreenContent (inner of the ScrollView) with the useScrollIntoView and refs
51function ScreenContent() {
52  const scrollIntoView = useScrollIntoView();
53  const viewRef = useRef();
54
55  return (
56    <>
57      <Button
58        onPress={() => {
59          scrollIntoView(viewRef.current, options);
60        }}
61      >
62        Scroll a view ref into view
63      </Button>
64
65      <View style={{ height: 100000 }}>
66        <Text>Some long ScrollView content</Text>
67      </View>
68
69      <View ref={viewRef}>
70        <Text>Will be scrolled into view on button press</Text>
71      </View>
72    </>
73  );
74}
75
76// Or implement ScreenContent (inner of the ScrollView) with class + declarative ScrollIntoView component
77class ScreenContent extends React.Component {
78  render() {
79    return (
80      <>
81        <ScrollIntoView>
82          <Text>This will scroll into view on mount</Text>
83        </ScrollIntoView>
84
85        <ScrollIntoView align="center">
86          <Text>This will scroll into view on mount and will be centered</Text>
87        </ScrollIntoView>
88
89        <ScrollIntoView animated={false}>
90          <Text>This will scroll into view on mount without any animation</Text>
91        </ScrollIntoView>
92
93        <ScrollIntoView immediate={true}>
94          <Text>
95            This will not throttle scrollIntoView calls, as by default it does
96            not make much sense to scroll into view multiple elements at the
97            same time...
98          </Text>
99        </ScrollIntoView>
100
101        <ScrollIntoView enabled={false}>
102          <Text>This will scroll into view whenever enabled becomes true</Text>
103        </ScrollIntoView>
104
105        <ScrollIntoView scrollIntoViewKey="some string">
106          <Text>
107            This will scroll into view whenever scrollIntoViewKey changes
108          </Text>
109        </ScrollIntoView>
110
111        <ScrollIntoView
112          onMount={false}
113          onUpdate={true}
114          scrollIntoViewKey="some string"
115        >
116          <Text>
117            This will scroll into on update (if it becomes enabled, or key
118            changes)
119          </Text>
120        </ScrollIntoView>
121
122        <ScrollIntoView scrollIntoViewOptions={options}>
123          <Text>
124            This will scroll into view on mount with custom option props
125          </Text>
126        </ScrollIntoView>
127
128        <View>
129          <ScrollIntoView
130            enabled={false}
131            ref={ref => (this.scrollIntoViewRef = ref)}
132          >
133            <Text>This will scroll into view when the button is pressed</Text>
134          </ScrollIntoView>
135          <Button
136            title="Make above text scroll into view with custom options"
137            onPress={() =>
138              this.scrollIntoViewRef.scrollIntoView(scrollIntoViewOptions)
139            }
140          />
141        </View>
142      </>
143    );
144  }
145}

You can also configure the HOC:

1const CustomScrollView = wrapScrollViewConfigured({
2  // SIMPLE CONFIG:
3  // ScrollIntoView default/fallback options
4  options: scrollIntoViewOptions,
5
6  // ADVANCED CONFIG:
7  // Use this if you use a ScrollView wrapper that does not use React.forwardRef()
8  refPropName: 'ref',
9  // unwraps the ref that the wrapped ScrollView gives you (this lib need the bare metal ScrollView ref)
10  getScrollViewNode: ref => ref,
11  // fallback value for throttling, can be overriden by user with props
12  scrollEventThrottle: 16,
13})(ScrollView);

All these hoc configurations can also be provided to the CustomScrollView as props.

Demos:

You can run the example folder as an Expo app with yarn start

It is also published on Expo

Recipes

Using in forms:

The integration with form libraries like Formik and Redux-form is very simple (see Formik example)

• By default, the first error field of the form will reveal itself
• enabled={!!error} means we'll only scroll into view fields that have an error
• scrollIntoViewKey={submitCount} means we'll scroll into view fields which still have errors on every Formik submit attempt (submitCount is provided by Formik)

Using with react-native-keyboard-aware-scroll-view

KeyboardAwareScrollView does not forward refs by default so we need to obtain ref by using the innerRef prop:

const ScrollIntoViewScrollView = wrapScrollViewConfigured({
  refPropName: 'innerRef',
})(KeyboardAwareScrollView);

TODOs:

• Tests
• Universal/Web support
• Support horizontal ScrollView?

Contribute

If your changes are impactful, please open an issue first.

License

MIT

Some code is inspired from contribution of @sebasgarcep of an initial scrollIntoView support for react-native-keyboard-aware-scroll-view

Hire a freelance expert

Looking for a React/ReactNative freelance expert with more than 5 years production experience? Contact me from my website or with Twitter.