Migration Guide to v5.x#

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

🎯 What's New in v5.x#

Dynamic Sizing (Auto-sizing)#

The biggest feature in v5.x is automatic dimension calculation. You no longer need to manually specify width and height props!

Expo 54 Support#

Full compatibility with Expo SDK 54 and the latest React Native ecosystem.

📦 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",
  "react-native-reanimated": ">=4.0.0",
  "react-native-worklets": ">=0.5.0"
}

💥 Breaking Changes#

1. React Native Reanimated v4#

Required: Upgrade to react-native-reanimated@^4.1.0

npm install react-native-reanimated@^4.1.0

Follow the Reanimated v4 migration guide for any breaking changes.

2. React Native Worklets (New Dependency)#

Required: Install react-native-worklets@^0.5.1

npm install react-native-worklets@^0.5.1

This package is required by Reanimated v4 and replaces the deprecated runOnJS function with scheduleOnRN.

✨ New Features#

Dynamic Sizing#

The most requested feature! Carousel now automatically measures container dimensions:

// ✅ v5.x - Auto-sizing (beta)
<Carousel
  data={data}
  renderItem={renderItem}
  // width and height are now optional!
  // Carousel automatically measures container
/>

// ✅ v5.x - 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 (v5 beta)#

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