@sellpy/react-native-scroll-anchor v0.1.1

@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

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

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

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

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