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

``sh
yarn add react-native-scroll-registry
`

or

`sh
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

$3

Creates a shared registry for scroll targets.

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

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

---

$3

Returns a scrollTo function.

`ts
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

$3

`tsx
const scrollRef = useRef(null);
const containerRef = useRef(null);

const { registry, registerView } = useScrollRegistry();

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



{items.map(item => (

))}



scrollTo("item-5")} />
`

---

$3

`tsx
const listRef = useRef(null);

const { registry, registerIndex } = useScrollRegistry();

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

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

scrollTo("item-10")} />
`

---

$3

Just set the axis:

`ts
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