feat!: Dynamic sizing with itemWidth/itemHeight props & modernized style API (#853)

* feat: update carousel examples and documentation for dynamic sizing support

* chore: add changeset

* fix: update deprecation messages for width and height props in TCarouselProps to clarify usage

* feat: add itemWidth and itemHeight props for explicit snapping in carousels

* chore: update git ignore file

* test: add unit tests for itemWidth and itemHeight props in carousel component

* test: simplify carousel component test rendering for better readability

* test: add overscroll prevention test for small page size

* test: add unit tests for Pagination component to validate size prop and rendering behavior

Author: dohooo

.changeset/blue-news-stare.md

@@ -0,0 +1,6 @@
+---
+"react-native-reanimated-carousel": minor
+---
+
+- add `itemWidth`/`itemHeight` props so horizontal and vertical carousels can define their snapping step explicitly (e.g. to show multiple cards per page)
+- default behaviour still falls back to the carousel container size or legacy `width`/`height` props

.changeset/odd-news-carry.md

@@ -0,0 +1,29 @@
+---
+"react-native-reanimated-carousel": minor
+---
+
+## ✨ Style API refresh
+
+- `style` now controls the outer carousel container (positioning, width/height, margins).
+- New `contentContainerStyle` replaces `containerStyle` for styling the scrollable content.
+- `width` and `height` props are deprecated; define size via `style` instead.
+
+### Migration Example
+
+```tsx
+// Before
+<Carousel
+  width={300}
+  height={200}
+  containerStyle={{ paddingHorizontal: 16 }}
+/>
+
+// After
+<Carousel
+  style={{ width: 300, height: 200 }}
+  contentContainerStyle={{ paddingHorizontal: 16 }}
+/>
+```
+
+- Any layout logic still works; simply move `width`/`height` into `style` and container tweaks into `contentContainerStyle`.
+- `contentContainerStyle` runs on the JS thread—avoid adding `opacity` / `transform` there if you rely on built-in animations.

.gitignore

@@ -81,4 +81,7 @@ coverage/
 .issue-tasks/
 
 # Agents Docs
-*.local.md
+*.local.md
+
+# Claude
+CLAUDE.md

CHANGELOG.md

@@ -6,6 +6,37 @@
 
 - [#850](https://github.com/dohooo/react-native-reanimated-carousel/pull/850) [`9b388e6`](https://github.com/dohooo/react-native-reanimated-carousel/commit/9b388e6f6237126c4ed25c2442c4b788aad7adf6) Thanks [@dohooo](https://github.com/dohooo)! - # 🎯 Support for Expo 54 & Dynamic Sizing
 
+- Style props refactoring:
+
+  - **BREAKING CHANGE**: The styling props have been refactored for clarity and consistency with React Native's `ScrollView`.
+  - **DEPRECATED**: `width` and `height` props are now deprecated. Please use the `style` prop to define component size.
+  - **NEW**: The `style` prop now controls the outer container's style and is the primary way to set `width` and `height`.
+  - **NEW**: A new `contentContainerStyle` prop has been added to control the style of the inner scrollable content.
+
+  #### Migration Guide
+
+  **Before:**
+  ```jsx
+  <Carousel
+    width={300}
+    height={200}
+    style={{ backgroundColor: 'red' }} // Applied to inner container
+    containerStyle={{ margin: 10 }} // Applied to outer container
+  />
+  ```
+
+  **After:**
+  ```jsx
+  <Carousel
+    style={{ 
+      width: 300, 
+      height: 200, 
+      margin: 10 
+    }} // Applied to outer container
+    contentContainerStyle={{ backgroundColor: 'red' }} // Applied to inner container
+  />
+  ```
+
   ## ✨ Major Features
 
   ### Dynamic Sizing Support

example/app/app/demos/basic-layouts/left-align/demo.tsx

@@ -10,13 +10,11 @@ function Index() {
     <View id="carousel-component" dataSet={{ kind: "basic-layouts", name: "left-align" }}>
       <Carousel
         loop={true}
-        width={430}
-        height={258}
         snapEnabled={true}
         pagingEnabled={true}
         autoPlayInterval={2000}
         data={defaultDataWith6Colors}
-        style={{ width: "100%" }}
+        style={{ width: 430, height: 258 }}
         onSnapToItem={(index) => console.log("current index:", index)}
         renderItem={renderItem({ rounded: true, style: { marginRight: 8 } })}
       />

example/app/app/demos/basic-layouts/left-align/index.tsx

@@ -6,7 +6,8 @@ import { CaptureWrapper } from "@/store/CaptureProvider";
 import { renderItem } from "@/utils/render-item";
 import * as React from "react";
 import { View } from "react-native";
-import type { ICarouselInstance } from "react-native-reanimated-carousel";
+import type { StyleProp, ViewStyle } from "react-native";
+import type { ICarouselInstance, TCarouselProps } from "react-native-reanimated-carousel";
 import Carousel from "react-native-reanimated-carousel";
 
 function Index() {
@@ -18,23 +19,31 @@ function Index() {
       autoPlayInterval: 2000,
       autoPlayReverse: false,
       data: defaultDataWith6Colors,
-      height: 258,
       loop: true,
       pagingEnabled: true,
       snapEnabled: true,
       vertical: false,
-      width: window.width,
     },
   });
 
+  const {
+    width: _ignoredWidth,
+    height: _ignoredHeight,
+    ...restSettings
+  } = advancedSettings as TCarouselProps;
+
   return (
     <View style={{ flex: 1 }}>
       <CaptureWrapper>
         <Carousel
-          {...advancedSettings}
+          {...restSettings}
           ref={ref}
-          style={{ width: "100%" }}
-          width={constants.PAGE_WIDTH * 0.75}
+          style={{ width: window.width, height: 258 }}
+          contentContainerStyle={{
+            width: window.width / 2,
+            height: 258,
+            overflow: "visible",
+          }}
           onSnapToItem={(index) => console.log("current index:", index)}
           renderItem={renderItem({ rounded: true, style: { marginRight: 8 } })}
         />

example/app/app/demos/basic-layouts/normal/demo.tsx

@@ -4,6 +4,8 @@ import { View } from "react-native";
 import { useSharedValue } from "react-native-reanimated";
 import Carousel from "react-native-reanimated-carousel";
 
+import { window } from "@/constants/sizes";
+
 const defaultDataWith6Colors = ["#B0604D", "#899F9C", "#B3C680", "#5C6265", "#F5D399", "#F1F1F1"];
 
 function Index() {
@@ -14,14 +16,12 @@ function Index() {
       <Carousel
         testID={"xxx"}
         loop={true}
-        width={430}
-        height={258}
         snapEnabled={true}
         pagingEnabled={true}
         autoPlayInterval={2000}
         data={defaultDataWith6Colors}
         defaultScrollOffsetValue={scrollOffsetValue}
-        style={{ width: "100%" }}
+        style={{ width: window.width, height: 258 }}
         onScrollStart={() => {
           console.log("Scroll start");
         }}

example/app/app/demos/basic-layouts/normal/index.tsx

@@ -5,8 +5,9 @@ import { useAdvancedSettings } from "@/hooks/useSettings";
 import { CaptureWrapper } from "@/store/CaptureProvider";
 import { renderItem } from "@/utils/render-item";
 import * as React from "react";
+import type { StyleProp, ViewStyle } from "react-native";
 import { useSharedValue } from "react-native-reanimated";
-import type { ICarouselInstance } from "react-native-reanimated-carousel";
+import type { ICarouselInstance, TCarouselProps } from "react-native-reanimated-carousel";
 import Carousel from "react-native-reanimated-carousel";
 import { Stack } from "tamagui";
 
@@ -20,12 +21,10 @@ function Index() {
       autoPlayInterval: 2000,
       autoPlayReverse: false,
       data: defaultDataWith6Colors,
-      height: 258,
       loop: true,
       pagingEnabled: true,
       snapEnabled: true,
       vertical: false,
-      width: window.width,
     },
   });
 
@@ -37,7 +36,10 @@ function Index() {
           ref={ref}
           defaultScrollOffsetValue={scrollOffsetValue}
           testID={"xxx"}
-          style={{ width: "100%" }}
+          style={{
+            height: 258,
+            width: window.width,
+          }}
           onScrollStart={() => {
             console.log("Scroll start");
           }}

example/app/app/demos/basic-layouts/parallax/demo.tsx

@@ -15,20 +15,21 @@ function Index() {
       <Carousel
         autoPlayInterval={2000}
         data={defaultDataWith6Colors}
-        height={258}
         loop={true}
         pagingEnabled={true}
         snapEnabled={true}
-        width={window.width}
         style={{
           width: window.width,
+          height: 258,
         }}
         mode="parallax"
         modeConfig={{
           parallaxScrollingScale: 0.9,
           parallaxScrollingOffset: 50,
         }}
-        onProgressChange={progress}
+        onProgressChange={(offsetProgress, absoluteProgress) => {
+          progress.value = absoluteProgress;
+        }}
         renderItem={renderItem({ rounded: true })}
       />
     </View>

example/app/app/demos/basic-layouts/parallax/index.tsx

@@ -23,12 +23,10 @@ function Index() {
       autoPlayInterval: 2000,
       autoPlayReverse: false,
       data: defaultDataWith6Colors,
-      height: 258,
       loop: true,
       pagingEnabled: true,
       snapEnabled: true,
       vertical: false,
-      width: PAGE_WIDTH,
     },
   });
 
@@ -40,13 +38,16 @@ function Index() {
           {...advancedSettings}
           style={{
             width: PAGE_WIDTH,
+            height: 258,
           }}
           mode="parallax"
           modeConfig={{
             parallaxScrollingScale: 0.9,
             parallaxScrollingOffset: 50,
           }}
-          onProgressChange={progress}
+          onProgressChange={(offsetProgress, absoluteProgress) => {
+            progress.value = absoluteProgress;
+          }}
           renderItem={renderItem({ rounded: true })}
         />
       </CaptureWrapper>