README.md

@sellpy/react-native-scroll-anchor ⚓️

Hooks and utilities to simplify scrolling to elements (anchors) in React Native.

• Easy to use 🚀
• Lightweight and fast ⚡️
• Zero dependencies 📦

Installation

npm install @sellpy/react-native-scroll-anchor

Quickstart

import React, { useRef } from 'react';
import { Button, ScrollView, TextInput, View } from 'react-native';
import {
  Anchor,
  ScrollAnchorProvider,
  useScrollAnchor,
} from '@sellpy/react-native-scroll-anchor';

export default function App() {
  const scrollRef = React.useRef<ScrollView>(null);

  const methods = useScrollAnchor(scrollRef);
  const { scrollTo, onScroll } = methods;

  return (
    <ScrollAnchorProvider {...methods}>
      <Button onPress={() => scrollTo('books')} title="View books" />
      <ScrollView onScroll={onScroll} scrollEventThrottle={32} ref={scrollRef}>
        <Anchor name="movies">
          <MovieList />
        </Anchor>
        <Anchor name="books">
          <BookList />
        </Anchor>
      </ScrollView>
    </ScrollAnchorProvider>
  );
}

---

Hooks

useScrollAnchor

The useScrollAnchor hook is used to register and unregister anchors, scroll to anchors, and listen to scroll events.

import { useScrollAnchor } from '@sellpy/react-native-scroll-anchor';

export function MyComponent() {
  const ref = useRef(null);
  const { register, unregister, scrollTo, timeoutOnScroll, onScroll } =
    useScrollAnchor(ref, {
      onAnchorReachedX: (name) =>
        console.log('Reached anchor on x-axis:', name),
      onAnchorReachedY: (name) =>
        console.log('Reached anchor on y-axis:', name),
    });

  return (
    <ScrollView
      onScroll={onScroll}
      scrollEventThrottle={32}
      ref={scrollRef}
    ></ScrollView>
  );
}

Args

Name	Type	Default	Description
ref	RefObject<ScrollView>		The ref of the ScrollView component
options	ScrollAnchorOptions	{}	Options

Returns ScrollAnchorMethods

---

useAnchorRef

Another way to register an anchor is by using the useAnchorRef hook. This hook is useful when you want to register an anchor ref without using the <Anchor/> component.

This component requires the ScrollAnchorProvider to be present in the component tree.

import { useAnchorRef } from '@sellpy/react-native-scroll-anchor';

export function MyComponent() {
  const ref = useAnchorRef('item');

  return (
    <View ref={ref}>
      <Text>Awesome Item</Text>
    </View>
  );

Args

Name	Type	Default	Description
name	string		The name of the anchor

Returns RefObject<NativeView>

Components

ScrollAnchorProvider

Sets up a provider enabling usage of <Anchor /> and useAnchorRef in the component tree.

import {
  ScrollAnchorProvider,
  useScrollAnchor,
} from '@sellpy/react-native-scroll-anchor';
import { ScrollView } from 'react-native';

export function MyComponent() {
  const scrollViewRef = useRef<ScrollView>(null);
  const methods = useScrollAnchor(ref);

  return (
    <ScrollAnchorProvider {...methods}>
      <ScrollView
        ref={scrollViewRef}
        onScroll={methods.onScroll}
        scrollEventThrottle={16}
      >
        <MyAnchoredComponent />
      </ScrollView>
    </ScrollAnchorProvider>
  );
}

Props

Name	Type	Default	Description
children	ReactNode		The children to render
...methods	ScrollAnchorMethods		Provide all methods returned form useScrollAnchor

Anchor

The <Anchor/> component is used to wrap a component that you want to scroll to.

This component requires the ScrollAnchorProvider to be present in the component tree.

import { Anchor } from '@sellpy/react-native-scroll-anchor';

<Anchor name="item">
  <MyAnchoredComponent />
</Anchor>;

Props

Name	Type	Default	Description
name	string		The name of the anchor. You can scroll to this anchor by calling scrollTo()

Types

ScrollAnchorOptions

interface ScrollAnchorOptions {
  /* Throttles onAnchorReachedX, onAnchorReachedY callbacks per anchor name as well as the scrollTo method. The number is in MS */
  throttle?: number /* default: 200 (ms) */;

  /* Offset for the x-axis when scrolling to an anchor */
  offsetX?: number /* default: 0 */;

  /* Offset for the y-axis when scrolling to an anchor */
  offsetY?: number /* default: 0 */;

  /* Callback when an anchor is reached on the x-axis. Requires binding of `onScroll` between referenced `ScrollView` and returned `onScroll` method */
  onAnchorReachedX?: (name: string) => void;

  /* Callback when an anchor is reached on the y-axis. Same requriements as for onAnchorReachedX */
  onAnchorReachedY?: (name: string) => void;

  /* If true, we make sure onAnchorReachedX and onAnchorReachedY are called when scrolling. They will be called with the nearest anchor */
  keepInBounds?: boolean /* default: false */;
}

ScrollAnchorMethods

interface ScrollAnchorMethods {
  /* Register an anchor with a name and a ref. */
  register: (name: string, ref: React.RefObject<NativeComponent>) => void;

  /* Unregister an anchor by name. */
  unregister: (name: string) => void;

  /* Scroll to an anchor by name. */
  scrollTo: (name: string) => void;

  /* Timeout onScroll manually, this won't cause onAnchorReachedX or onAnchorReachedY to be called. */
  timeoutOnScroll: (timeMs: number) => void;

  /* The onScroll event handler. Pass this to the ScrollView component. **NOTE: this is required for if onScrollAnchorReachedX or onScrollAnchorReachedY should be called.** */
  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;

  /* The refs of all registered anchors, key is anchor name povided */
  anchorRefs: Record<string, React.RefObject<NativeComponent>>;
}

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---