Migration Guide to v5 beta

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

🎯 What's New in v5 beta

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",
  "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@beta 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@beta react-native-reanimated react-native-worklets react-native-gesture-handler

Follow the Reanimated installation guide (opens in a new tab) and compatibility table (opens in a new tab). 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 beta - Auto-sizing
<View style={{ height: 200 }}>
  <Carousel
    style={{ flex: 1 }}
    data={data}
    renderItem={renderItem}
  />
</View>
 
// ✅ v5 beta - 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 beta

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