dohooo/react-native-reanimated-carousel

README

react-native-reanimated-carousel

A performant, customizable carousel for React Native, powered by Reanimated and Gesture Handler.

What you can build

Each one is a full app screen built on <Carousel>. Browse all 20 scenes to drag them live and copy the code.

Migrating from v4

v5 requires React Native 0.80+, Reanimated 4.1+ and React Native Worklets 0.5+ (Expo SDK 54+). Apps still on Reanimated 3 can keep using v4 until they upgrade.

To upgrade, give this prompt to your AI coding agent:

Read https://rn-carousel.dev/migration-v5.md and upgrade react-native-reanimated-carousel to v5 in this project, then summarize what changed for my review.

v5 highlights

A smaller, named-only API with descriptive TypeScript types.
Container sizing through style, with optional itemSize for a custom page distance.
Explicit layout, itemAnimation, snapMode, and orientation contracts.
Continuous logical progress plus signed pixel-level scrollOffsetValue.
One Pagination component with loop-aware interpolation and accessible interactive dots.
Stable item identity through keyExtractor, horizontal RTL normalization, and package exports.

Installation

Expo projects should let Expo select compatible Reanimated and Worklets versions:

npx expo install react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler

React Native Community CLI projects can use their package manager:

yarn add react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler

Follow the official setup instructions for Reanimated and Gesture Handler.

Quick start

import * as React from "react";
import { Text, useWindowDimensions, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Carousel } from "react-native-reanimated-carousel";

const data = ["First", "Second", "Third"];

export default function App() {
  const { width } = useWindowDimensions();

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <View style={{ flex: 1, justifyContent: "center" }}>
        <Carousel
          style={{ width, height: 200 }}
          data={data}
          renderItem={({ item }) => (
            <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
              <Text>{item}</Text>
            </View>
          )}
        />
      </View>
    </GestureHandlerRootView>
  );
}

loop defaults to false in v5. Add loop when infinite wrapping is part of the product behavior.

Version compatibility

Carousel	Expo SDK	React Native	Reanimated	Gesture Handler	Worklets
v5	54–57 validated	0.80+	4.1.0+	>=2.9.0 <4.0.0	0.5.0+
v4.x (EOL)	50–53	0.70.3+	3.0.0+	2.9.0+	—
v3.x (EOL)	47–49	0.66.0+	2.0.0+	2.0.0+	—

Reanimated and Worklets must be a compatible pair. Expo users should use expo install; other projects should consult the Reanimated compatibility table.

License

MIT