react-native-scroll-registry

A small, type-safe utility for scrolling to items by key in React Native.

It provides a single mental model that works for both:

• ScrollView (measure-based scrolling)
• FlatList (index-based, virtualization-safe scrolling)

Register items with a key → call scrollTo(key).

Features

• Unified API for ScrollView and FlatList
• Works with vertical and horizontal lists
• Safe for large, virtualized lists (FlatList)
• Zero dependencies
• TypeScript-first
• No native code

Installation

yarn add react-native-scroll-registry

or

npm install react-native-scroll-registry

Core Concept

There are only two steps:

1. Register items with a unique key
2. Scroll to that key

Internally:

• ScrollView → uses layout measurement
• FlatList → uses scrollToIndex

You don’t need to care which one is used.

API

useScrollRegistry()

Creates a shared registry for scroll targets.

const { registry, registerView, registerIndex } = useScrollRegistry();

| Function | Used for | Description | |------|------|------| | registerView(key) | ScrollView | Registers a view ref | | registerIndex(key, index) | FlatList | Registers an item index |

useScrollTo(options)

Returns a scrollTo function.

const scrollTo = useScrollTo({
  scrollViewRef,
  containerRef,
  registry,
  axis: "vertical"
});

Options

| Option | Description | |------|------| | scrollViewRef | Ref to ScrollView | | flatListRef | Ref to FlatList | | containerRef | Required for ScrollView | | registry | Registry from useScrollRegistry | | axis | "vertical" (default) or "horizontal" |

Examples

ScrollView (Vertical)

const scrollRef = useRef<ScrollView>(null);
const containerRef = useRef<View>(null);

const { registry, registerView } = useScrollRegistry();

const scrollTo = useScrollTo({
  scrollViewRef: scrollRef,
  containerRef,
  registry,
});

<ScrollView ref={scrollRef}>
  <View ref={containerRef}>
    {items.map(item => (
      <View key={item.id} ref={registerView(item.id)} />
    ))}
  </View>
</ScrollView>

<Button title="Go to item-5" onPress={() => scrollTo("item-5")} />

FlatList (Vertical)

const listRef = useRef<FlatList>(null);

const { registry, registerIndex } = useScrollRegistry();

const scrollTo = useScrollTo({
  flatListRef: listRef,
  registry,
});

<FlatList
  ref={listRef}
  data={data}
  renderItem={({ item, index }) => {
    registerIndex(item.id, index);
    return <Item />;
  }}
/>

<Button title="Go to item-10" onPress={() => scrollTo("item-10")} />

Horizontal Lists

Just set the axis:

useScrollTo({ axis: "horizontal", ... })

Works for both ScrollView and FlatList.

Notes & Best Practices

• Use keys that are stable (IDs, not array indices)
• ScrollView requires all items to be mounted
• FlatList is recommended for large lists
• Do not mix registerView and registerIndex for the same list