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 (opens in a new tab) 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).