FAQ

Optimizing

When rendering a large number of elements, you can use the 'windowSize' property to control how many items of the current element are rendered. The default is full rendering. After testing without this property, frames will drop when rendering 200 empty views. After setting this property, rendering 1000 empty views is still smooth. (The specific number depends on the phone model tested)

Used in ScrollView/FlatList

#143 (opens in a new tab) - Carousel suppresses ScrollView/FlatList scroll gesture handler: When a horizontal carousel is nested in a vertical ScrollView or FlatList, configure the pan gesture so small horizontal movement does not capture the parent scroll. For example, use Gesture Handler's activeOffsetX (opens in a new tab):

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

RTL

Support to RTL mode with no more configuration needed. But in RTL mode, need to manually set the autoPlayReverse props for autoplay to control scrolling direction.

Expo

Install the v5 beta and its native peers with expo install so Expo selects compatible versions:

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

The v5 beta requires React Native 0.80+, Reanimated 4.1+, and React Native Worklets 0.5+. See the v5 migration guide for the validated Expo matrix and setup notes.

Working principle

How it works?

How to run the example app

Build the package, then install and run the Expo app from its current location:

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

Run the library checks from the repository root:

yarn test
yarn types
yarn lint