Migration Guide to v5.x#

This guide will help you migrate your application from react-native-reanimated-carousel v4.x to v5.

🎯 What's New in v5#

Dynamic Sizing (Auto-sizing)#

The carousel can now measure the main-axis size provided by its parent layout and respond when that size changes. The parent must still provide enough layout constraints for the carousel to be visible.

Current Expo Support#

The release matrix validates Expo SDK 54, 55, 56, and 57 with React Native 0.81, 0.83, 0.85, and 0.86 respectively. It type-checks a packed consumer, exports Web, and builds Android; native iOS and Android E2E currently run on Expo 54.

📦 Version Requirements#

Before upgrading, ensure your project meets these version requirements:

{
  "react": ">=18.0.0",
  "react-native": ">=0.80.0",
  "react-native-gesture-handler": ">=2.9.0 <4.0.0",
  "react-native-reanimated": ">=4.1.0",
  "react-native-worklets": ">=0.5.0"
}

💥 Breaking Changes#

1. Container and content styles#

The v4 style props map to v5 as follows:

style now describes the outer carousel container. Use contentContainerStyle for styles that previously targeted the inner carousel content.

2. React Native Reanimated v4#

Required: Upgrade to Reanimated 4.1 or newer and install a compatible Worklets version.

Expo projects should let Expo choose the matching versions:

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

React Native Community CLI projects can install the packages with their package manager:

npm install react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler

Follow the Reanimated installation guide and compatibility table. Community CLI projects must replace react-native-reanimated/plugin with react-native-worklets/plugin in their Babel configuration.

Reanimated 4 requires React Native's New Architecture. After changing Reanimated, Worklets, or Babel configuration, rebuild the native application (and reinstall iOS pods when applicable).

3. React Native Worklets (New Dependency)#

Worklet-specific APIs moved to react-native-worklets. Reanimated still re-exports older APIs such as runOnJS for compatibility, but those imports are deprecated; new code should use APIs such as scheduleOnRN from react-native-worklets.

✨ New Features#

Dynamic Sizing#

The carousel measures dimensions assigned by its parent layout. For example, a horizontal carousel can fill a parent with a responsive width and a defined height:

// ✅ v5 - Auto-sizing
<View style={{ height: 200 }}>
  <Carousel
    style={{ flex: 1 }}
    data={data}
    renderItem={renderItem}
  />
</View>

// ✅ v5 - Still works (explicit sizing via style prop)
<Carousel
  style={{ width: 300, height: 200 }}
  data={data}
  renderItem={renderItem}
/>

Notes on sizing vs page size#

• style.width / style.height describe the container size (recommended).
• itemWidth / itemHeight describe the page size (snap distance & animation progress per page). They are not the same as container size.

New naming in v5#

defaultScrollOffsetValue is deprecated in favor of scrollOffsetValue (same behavior, clearer name).