react-native-reanimated-carousel v5: a Reanimated carousel for iOS, Android and Web

What react-native-reanimated-carousel is for

Swiper and carousel widgets look trivial until you build one. Snap points, gesture velocity, RTL direction, loop wrapping and item identity all interact, and the naive version re-renders the whole list on every frame. This package exists to absorb that work: it is a React Native swiper and carousel component implemented on Reanimated and Gesture Handler, and the README states it supports iOS, Android and Web. The audience is React Native app teams that need a snapping, draggable page view with custom animation, not a static image strip. The package ships TypeScript types from src/index.tsx and a compiled build in lib/module and lib/commonjs, so it is consumed like any other npm dependency. The project is MIT licensed and the repository is not archived; the most recent push was on 2026-08-08, which is when v5.1.1 was released. It is a component library, not a framework, so nothing about your navigation or state layer changes.

How v5 works: layout, progress and scrollOffsetValue

The v5 API is deliberately smaller and named-only, and the README lists the contracts it exposes: layout, itemAnimation, snapMode and orientation. Container sizing moved to style, with an optional itemSize when you want a page distance that differs from the container width. Two values drive custom animation. progress is a continuous logical value, so it keeps counting across loop boundaries instead of resetting at each wrap. scrollOffsetValue is signed and measured in pixels, which is what you want for parallax or scale effects tied to physical travel. Those two are not interchangeable, and the README treats them as separate contracts rather than one number with two names. Pagination is a single component with loop-aware interpolation and interactive dots that expose accessibility behaviour. Item identity is handled by keyExtractor, which matters when your data array reorders, and horizontal RTL is normalized inside the package rather than left to each screen. The package also declares exports, so bundlers resolve the react-native entry to src/index.tsx and the import and require entries to the compiled lib output.

Installing react-native-reanimated-carousel in an Expo or CLI project

The README gives two install paths and they are not equivalent. Expo projects should let Expo pick matching Reanimated and Worklets versions, because those two libraries must be a compatible pair:

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

React Native Community CLI projects use their own package manager instead. The README shows yarn:

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

After installing, follow the official setup instructions for Reanimated and Gesture Handler linked from the README. The carousel does not configure those libraries for you, and skipping that step is the most common way to get a blank or frozen view. For a first real use, the README's quick start wraps the app in GestureHandlerRootView and sizes the carousel from the window width:

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>
  );
}

You should see three labelled pages that snap as you drag. One detail catches people out: loop defaults to false in v5, so add loop only when infinite wrapping is part of the product behaviour. In v4 the default was the other way around.

The version pairing is the real constraint

The README publishes a compatibility table, and it is the first thing to read before upgrading. v5 is validated against Expo SDK 54 to 57, React Native 0.80+, Reanimated 4.1.0+, Gesture Handler >=2.9.0 <4.0.0, and Worklets 0.5.0+. The v4.x and v3.x lines are both marked EOL in that table, and they map to older Expo and Reanimated versions. This is a hard boundary, not a suggestion: Reanimated and Worklets must be a compatible pair, and Expo users are told to use expo install so the resolver picks versions that match. If your app is pinned to Expo SDK 53 or React Native 0.79, v5 is not the version you install. The second constraint is migration cost. v5 is a breaking change with a smaller named API, container sizing through style, and loop flipped to false by default. The README points to a migration guide at rn-carousel.dev/migration-v5, and package.json ships a codemod binary named rnrc-v5-codemod at scripts/codemods/v5.mjs. A codemod can rename props, but it cannot decide whether your carousel should loop or how your item width relates to the container. Those are product decisions you make by hand.

Where this carousel is the wrong tool

It is a gesture-driven, animated page view, and that is the whole scope. If you need a grid of cards that scrolls, a FlatList with numColumns is simpler and has no Reanimated 4 requirement. If your app cannot take a new Reanimated version, this package is the wrong dependency regardless of how good the component is, because the v5 line is built on Reanimated 4.1.0+ and the older lines are EOL. Web support is listed as a platform, but the repository carries a separate e2e-web directory and a Playwright config, which suggests web is exercised through its own test path rather than being the primary target; treat it as a supported surface to verify on your own stack. Heavy custom animation also has a cost: progress and scrollOffsetValue give you the hooks, but every animation you attach runs on the UI thread and is your responsibility to keep cheap. Finally, if your carousel is a marketing banner that changes once a session, the dependency weight is hard to justify.

react-native-snap-carousel and the alternative approach

The obvious alternative people search for is react-native-snap-carousel, and the difference is architectural rather than cosmetic. Snap-carousel predates Reanimated and drives its snapping through the older Animated API and ScrollView internals. This package instead delegates gesture recognition to Gesture Handler and animation to Reanimated, which is why the README can talk about progress and scrollOffsetValue as first-class values you interpolate against. The practical consequence is the dependency floor: snap-carousel does not require Reanimated 4.1.0 or Worklets 0.5.0, so it can fit an older app that this package cannot. In exchange you give up the named layout, itemAnimation, snapMode and orientation contracts, and the loop-aware Pagination component. A third option is to build the carousel yourself on a horizontal FlatList with paging enabled. That works for simple snapping and avoids the dependency entirely, but you then own RTL normalization, item identity through reordering, and every custom animation frame. Pick based on how much of that you want to write.

Licence and what maintenance costs you

The package is MIT licensed, which is permissive and imposes no source-disclosure obligation on your app. That is a statement about the licence text, not legal advice; if your organisation has a licence review process, this is a short one. Maintenance cost shows up in two places. The first is the dependency floor: v5 requires React Native 0.80+, Reanimated 4.1.0+ and Worklets 0.5.0+, so every future React Native or Expo upgrade has to keep that trio aligned, and Expo users are told to use expo install for exactly that reason. The second is the v5 API break itself. The repository keeps a CHANGELOG.md and an ARCHIVED.CHANGELOG.md, and package.json ships a codemod, so the upgrade path is documented rather than improvised. The last push was on 2026-08-08 and the latest release is v5.1.1, so the v5 line has had three releases since 2026-07-25: v5.0.0, v5.1.0 and v5.1.1. Budget for the migration as a real task, and read the migration guide before you start.

Editorial conclusion

Adopt it if your app already runs Reanimated 4.1.0+ and Gesture Handler 2.9.0+ on React Native 0.80+, because v5 is built against that pairing and the v4 line is marked EOL. Do not adopt it if you are pinned to Expo SDK 53 or below, since the compatibility table maps those to v4. Before writing any code, check your installed Reanimated and Worklets versions against the table, run the rnrc-v5-codemod script on the migration branch, and confirm which props your current code passes, because v5 moved sizing to style and made loop default to false.

Frequently asked questions

Official sources

1. dohooo/react-native-reanimated-carousel on GitHub
2. License: MIT
3. Project website
4. README
5. Releases