react-native-reanimated-carousel

The library splits operations between the UI thread (Worklets) and the JS thread to ensure smooth animations. Understanding this boundary is important for performance and debugging.

UI thread / Worklets handle:

• Animation properties: handlerOffset, progress, relativeProgress.
• Motion, visible ranges, layout transforms, and item animations.
• Gesture handlers and consumer gesture observers.
• Pagination interpolation.

JS thread handles:

• React rendering, renderItem, and keyExtractor.
• Configuration calls for onConfigurePanGesture.
• Refs and public lifecycle/progress callbacks.
• Layout events (onLayout), pagination presses, and accessibility label factories.

Cross-thread communication is managed explicitly using scheduleOnRN or scheduleOnUI.

When choosing between carousel libraries for React Native, consider the following performance characteristics:

• react-native-snap-carousel: May experience issues with infinite scrolling when swiping quickly (getting stuck or waiting for the next element to appear). It is better suited for scenarios where you want to see the content clearly at the junction points during a swipe.
• react-native-reanimated-carousel: Designed for high performance using a different architectural approach. It is specifically optimized to handle fast swiping (e.g., ten slides per second) without the stuttering or sticking issues common in other libraries.

The Carousel component is uncontrolled. To navigate or control the carousel after mounting, use the defaultIndex prop for the initial position and a CarouselRef to access imperative methods. Use React.useRef<CarouselRef>(null) to create the ref.

import * as React from "react";
import {
  Carousel,
  type CarouselRef,
} from "react-native-reanimated-carousel";

function ProductCarousel() {
  const ref = React.useRef<CarouselRef>(null);

  return (
    <Carousel
      ref={ref}
      data={products}
      keyExtractor={(product) => product.id}
      renderItem={({ item }) => <ProductCard product={item} />}
    />
  );
}

In v5, the mode and modeConfig props are replaced by a single layout prop. This is a manual migration step.

Example conversion:

From v4:

<Carousel
  mode="parallax"
  modeConfig={{
    parallaxScrollingOffset: 100,
    parallaxScrollingScale: 0.8,
    parallaxAdjacentItemScale: 0.64,
  }}
/>

To v5:

<Carousel
  layout={{
    type: "parallax",
    offset: 100,
    scale: 0.8,
    adjacentScale: 0.64,
  }}
/>

Layout field mappings:

Note: layout and itemAnimation are mutually exclusive.

To run the included Expo example app, build the package first, then navigate to the app directory to install dependencies and start the project.

yarn prepare
cd example/app
yarn install
yarn ios # or: yarn android / yarn web

Horizontal RTL is detected via I18nManager.isRTL.

• Data Order: Keep data in logical order. next(), autoplayDirection="forward", progress, and signed offset retain their standard meanings.
• Gestures: A physical right swipe advances the carousel in RTL.
• Animations: Custom itemAnimation callbacks receive logical progress. If you use direction-sensitive translateX values, you must mirror them manually in your application to account for RTL.

Autoplay is a controlled scheduler that triggers after the previous movement has settled.

Key Behaviors:

• Interval: The autoplayInterval is measured from the moment the previous movement settles, not from the start of the animation.
• Pausing: Autoplay automatically pauses during user interaction or any in-flight transition.
• Looping: With loop={false}, a rejected boundary command (trying to go past the end) will end the autoplay chain.
• Interaction: Setting scrollEnabled={false} affects pan input but does not stop autoplay or commands.

When nesting a horizontal Carousel inside a vertical ScrollView or FlatList, the carousel might suppress the parent's scroll gestures. To prevent small horizontal movements from capturing the parent scroll, use the onConfigurePanGesture prop to configure the pan gesture's activeOffsetX using react-native-gesture-handler.

<Carousel
  {...}
  onConfigurePanGesture={(gesture) => {
    gesture.activeOffsetX([-10, 10]);
  }}
/>

In v5, the Pagination component's dots are decorative and non-interactive by default. To make them interactive navigation controls, use the onPress prop to trigger scrollTo via the carousel ref.

<Pagination
  count={data.length}
  progress={progress}
  onPress={(index) => ref.current?.scrollTo({ index })}
/>

To use the carousel in an Expo Snack, you must explicitly declare react-native-worklets as a dependency because it is not currently bundled in Snack's runtime.

Note: While web player compatibility is verified, native Snack preview support is not yet officially claimed and requires manual device verification.

When updating the data prop, use keyExtractor to ensure the current item survives insertions or reordering. If the selected key exists, it remains selected. If the key disappears or no keyExtractor is provided, the old numeric index is clamped to the new range.

To select a newly added item, navigate using scrollTo inside a useEffect after the data update has been committed to React.

const [pendingIndex, setPendingIndex] = React.useState<number | null>(null);

function addProduct(product: Product) {
  setProducts((current) => {
    setPendingIndex(current.length);
    return [...current, product];
  });
}

React.useEffect(() => {
  if (pendingIndex === null || pendingIndex >= products.length) return;
  ref.current?.scrollTo({ index: pendingIndex });
  setPendingIndex(null);
}, [pendingIndex, products.length]);