refactor: deprecate width/height props in favor of style-based sizing (#873)

dohooo · web-flow · commit ffb59aac4154 · 2025-12-12T14:47:33.000+07:00
* chore: update .gitignore to exclude .claude file * refactor: deprecate width/height props in favor of style-based sizing - Add @deprecated annotations to width/height props - Prioritize style dimensions over legacy props - Add scrollOffsetValue as preferred alternative to defaultScrollOffsetValue - Update documentation, migration guide, and examples
diff --git a/.changeset/style-based-sizing.md b/.changeset/style-based-sizing.md
@@ -0,0 +1,41 @@
+---
+"react-native-reanimated-carousel": minor
+---
+
+# Deprecate width/height props in favor of style-based sizing
+
+## Changes
+
+### Deprecated Props
+- `width` and `height` props are now deprecated. Use `style={{ width: ..., height: ... }}` instead
+- `defaultScrollOffsetValue` is deprecated in favor of `scrollOffsetValue`
+
+### New Behavior
+- Carousel now prioritizes dimensions from `style` prop over legacy `width`/`height` props
+- When both `style` and legacy props are provided, `style` takes precedence
+
+### Migration
+
+**Before (v4 style):**
+```tsx
+<Carousel width={300} height={200} />
+```
+
+**After (v5 style):**
+```tsx
+<Carousel style={{ width: 300, height: 200 }} />
+```
+
+**Scroll offset:**
+```tsx
+// Before
+<Carousel defaultScrollOffsetValue={sharedValue} />
+
+// After
+<Carousel scrollOffsetValue={sharedValue} />
+```
+
+### Notes
+- Legacy props remain functional for backwards compatibility
+- Console warnings will guide migration in development mode
+- Full removal planned for next major version
diff --git a/.gitignore b/.gitignore
@@ -84,4 +84,5 @@ coverage/
 *.local.md
 
 # Claude
-CLAUDE.md
+CLAUDE.md
+.claude
diff --git a/README.md b/README.md
@@ -16,6 +16,12 @@
 -   [Getting Started](https://rn-carousel.dev)
 -   [Examples](https://rn-carousel.dev/Examples/summary)
 
+## v5 beta notes
+
+- **Sizing**: `style` controls the **container size**; `itemWidth`/`itemHeight` control the **page size** (snap distance & animation progress).
+- **Scroll offset shared value**: use `scrollOffsetValue` (recommended). `defaultScrollOffsetValue` is deprecated but still supported.
+- **Progress**: `onProgressChange` supports both a callback and `SharedValue<number>`.
+
 ## 📊 Version Compatibility
 
 | Carousel Version | Expo SDK | React Native | Reanimated | Gesture Handler | Worklets   |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -186,8 +186,10 @@ Input Props → Default Value Filling → Size Standardization → Data Processi
 
 **Core SharedValues**:
 ```typescript
-const handlerOffset = useSharedValue(defaultScrollOffsetValue || 0);
-const size = vertical ? height : width;
+const handlerOffset = scrollOffsetValue ?? defaultScrollOffsetValue ?? useSharedValue(0);
+// `size` is the "page size" used for snapping & animations:
+// itemWidth/itemHeight (preferred) -> style axis size -> deprecated width/height -> measurement
+const size = /* resolved page size */;
 const validLength = dataLength - 1;
 ```
 
diff --git a/example/app/app/demos/basic-layouts/normal/demo.tsx b/example/app/app/demos/basic-layouts/normal/demo.tsx
@@ -20,7 +20,7 @@ function Index() {
         pagingEnabled={true}
         autoPlayInterval={2000}
         data={defaultDataWith6Colors}
-        defaultScrollOffsetValue={scrollOffsetValue}
+        scrollOffsetValue={scrollOffsetValue}
         style={{ width: window.width, height: 258 }}
         onScrollStart={() => {
           console.log("Scroll start");
diff --git a/example/app/app/demos/basic-layouts/normal/index.tsx b/example/app/app/demos/basic-layouts/normal/index.tsx
@@ -34,7 +34,7 @@ function Index() {
         <Carousel
           {...advancedSettings}
           ref={ref}
-          defaultScrollOffsetValue={scrollOffsetValue}
+          scrollOffsetValue={scrollOffsetValue}
           testID={"xxx"}
           style={{
             height: 258,
diff --git a/example/app/app/demos/custom-animations/quick-swipe/demo.tsx b/example/app/app/demos/custom-animations/quick-swipe/demo.tsx
@@ -42,7 +42,7 @@ function Index() {
         loop={false}
         enabled // Default is true, just for demo
         ref={ref}
-        defaultScrollOffsetValue={scrollOffsetValue}
+        scrollOffsetValue={scrollOffsetValue}
         testID={"xxx"}
         contentContainerStyle={{ width: "100%" }}
         style={{ width: window.width, height: window.width / 2 }}
diff --git a/example/app/app/demos/custom-animations/quick-swipe/index.tsx b/example/app/app/demos/custom-animations/quick-swipe/index.tsx
@@ -48,7 +48,7 @@ function Index() {
           loop={false}
           enabled // Default is true, just for demo
           ref={ref}
-          defaultScrollOffsetValue={scrollOffsetValue}
+          scrollOffsetValue={scrollOffsetValue}
           testID={"xxx"}
           contentContainerStyle={{ width: "100%" }}
           style={{ width: window.width, height: window.width / 2 }}
diff --git a/example/website/pages/Examples/basic-layouts/normal.mdx b/example/website/pages/Examples/basic-layouts/normal.mdx
@@ -77,7 +77,7 @@ function Index() {
 				pagingEnabled={true}
 				autoPlayInterval={2000}
 				data={defaultDataWith6Colors}
-				defaultScrollOffsetValue={scrollOffsetValue}
+				scrollOffsetValue={scrollOffsetValue}
 				style={{ width: window.width, height: 258 }}
 				onScrollStart={() => {
 					console.log("Scroll start");
diff --git a/example/website/pages/Examples/custom-animations/quick-swipe.mdx b/example/website/pages/Examples/custom-animations/quick-swipe.mdx
@@ -89,7 +89,7 @@ function Index() {
 				loop={false}
 				enabled // Default is true, just for demo
 				ref={ref}
-				defaultScrollOffsetValue={scrollOffsetValue}
+				scrollOffsetValue={scrollOffsetValue}
 				testID={"xxx"}
 				contentContainerStyle={{ width: "100%" }}
 				style={{ width: window.width, height: window.width / 2 }}
diff --git a/example/website/pages/concepts.mdx b/example/website/pages/concepts.mdx
@@ -50,7 +50,9 @@ This is how it works in code.
 > I don't think I have explained this logic clearly, but this is a version that has been revised many times, it is a complicated process, if any partners have their own understanding, welcome to submit PR, we will make this explanation more clear.  
 > In my opinion, this part is undoubtedly very important for the initial stage of project development, but it is no longer so "important" at present, because the underlying content of this part will no longer change significantly. If you are interested in it, you can understand it, otherwise I don't think it is necessary to understand it.  
 
-1. First we need a unit `size` to help us calculate the scroll distance. When horizontal, `size` is equal to the `width` prop setting, when vertical, `size` is equal to the `height` prop setting.
+1. First we need a unit `size` to help us calculate the scroll distance. This `size` is the **page size**:
+   - If `itemWidth` / `itemHeight` is provided, `size` uses that.
+   - Otherwise, `size` falls back to the **container axis size** (prefer `style.width` / `style.height`, or legacy `width` / `height`, or layout measurement).
 
 2. Then we need a value `handlerOffset`, which is the current scroll distance, and it's a total value, if we scroll two, `handlerOffset` is equal to `size` * 2, if we scroll ten, `handlerOffset` is equal to `size` * 10.
 
diff --git a/example/website/pages/migration-v5.mdx b/example/website/pages/migration-v5.mdx
@@ -86,3 +86,12 @@ The most requested feature! Carousel now automatically measures container dimens
   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).
diff --git a/example/website/pages/props.mdx b/example/website/pages/props.mdx
@@ -49,11 +49,21 @@ Render carousel item
 
 ### `defaultScrollOffsetValue`
 
-The default animated value of the carousel.
+> @deprecated Use `scrollOffsetValue` instead.
+
+Legacy name for the carousel scroll offset shared value. If provided, the carousel will mutate it during gestures/animations.
+
+| type   | default | required |
+| ------ | ------- | -------- |
+| SharedValue\<number\> | -     | ❌      |
+
+### `scrollOffsetValue`
+
+The carousel scroll offset shared value (recommended). If provided, the carousel will mutate it during gestures/animations.
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| useSharedValue\<number\>\(0\) | -     | ❌      |
+| SharedValue\<number\> | -     | ❌      |
 
 ### `autoFillData`
 
@@ -75,21 +85,21 @@ Layout items vertically instead of horizontally
 
 > @deprecated Use `style` prop instead. e.g. `style={{ width: 300 }}`
 
-Specified carousel item width
+Specified carousel container width (legacy v4 API)
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| number \| undefined | '100%'     | ❌      |
+| number \| undefined | -     | ❌      |
 
 ### `height`
 
 > @deprecated Use `style` prop instead. e.g. `style={{ height: 200 }}`
 
-Specified carousel item height
+Specified carousel container height (legacy v4 API)
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| number \| undefined | '100%'     | ❌      |
+| number \| undefined | -     | ❌      |
 
 ### `mode`
 
@@ -109,23 +119,29 @@ Different modes correspond to different configurations. For details, see below\[
 
 ### `style`
 
-Style of the carousel container. This is the only place to define the component's size (`width`, `height`).
+Style of the carousel container (recommended for sizing).
+
+If `style.width` / `style.height` are not provided, the carousel will fall back to automatic measurement via layout — but the parent layout must still constrain the size (e.g. `flex: 1`, or a fixed size wrapper).
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| ViewStyle | \{\}     | ❌      |
+| StyleProp\<ViewStyle\> | \{\}     | ❌      |
 
 ### `itemWidth`
 
-Horizontal page size used for snapping and animations. Set this when you want multiple items visible within a single viewport.
+Horizontal **page size** used for snapping and animations.
+
+This is **not** the same as the container width. Use this when you want multiple items visible within a single viewport.
 
 | type   | default | required |
 | ------ | ------- | -------- |
 | number \| undefined | container width | ❌ |
 
 ### `itemHeight`
 
-Vertical page size used for snapping and animations. Set this when you want multiple rows visible at once in vertical mode.
+Vertical **page size** used for snapping and animations.
+
+This is **not** the same as the container height. Use this when you want multiple rows visible at once in vertical mode.
 
 | type   | default | required |
 | ------ | ------- | -------- |
@@ -137,7 +153,7 @@ Style of the carousel content container.
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| ViewStyle | \{\}     | ❌      |
+| StyleProp\<ViewStyle\> | \{\}     | ❌      |
 
 ### `defaultIndex`
 
@@ -221,7 +237,9 @@ Callback fired when scroll end
 
 ### `withAnimation`
 
-Specifies the scrolling animation effect
+Specifies the scrolling animation effect.
+
+If provided, it takes precedence over `scrollAnimationDuration`.
 
 | type   | default | required |
 | ------ | ------- | -------- |
@@ -250,7 +268,7 @@ The callback provides two parameters: `offsetProgress`:Total of offset distance
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| onProgressChange?: \(offsetProgress: number,absoluteProgress: number\) => void | -     | ❌      |
+| \(\(offsetProgress: number, absoluteProgress: number\) => void\) \| SharedValue\<number\> | -     | ❌      |
 
 ### `modeConfig`
 
@@ -306,7 +324,7 @@ Custom carousel config
 
 | type   | default | required |
 | ------ | ------- | -------- |
-| \(\) => \{type\?: 'negative' \| 'positive';viewCount\?: number;} | -     | ❌      |
+| \{type\?: 'negative' \| 'positive';viewCount\?: number;\} \| \(\) => \{type\?: 'negative' \| 'positive';viewCount\?: number;\} | -     | ❌      |
 
 ### `customAnimation`
 
diff --git a/src/components/ItemLayout.tsx b/src/components/ItemLayout.tsx
@@ -1,5 +1,6 @@
 import React from "react";
 import type { LayoutChangeEvent, ViewStyle } from "react-native";
+import { StyleSheet } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 import Animated, {
   useAnimatedStyle,
@@ -8,12 +9,12 @@ import Animated, {
 } from "react-native-reanimated";
 import { scheduleOnUI } from "react-native-worklets";
 
-import { TCarouselProps } from "src/types";
 import type { IOpts } from "../hooks/useOffsetX";
 import { useOffsetX } from "../hooks/useOffsetX";
 import type { IVisibleRanges } from "../hooks/useVisibleRanges";
 import type { ILayoutConfig } from "../layouts/stack";
 import { useGlobalState } from "../store";
+import type { TCarouselProps } from "../types";
 
 export type TAnimationStyle = NonNullable<TCarouselProps["customAnimation"]>;
 
@@ -29,7 +30,7 @@ export const ItemLayout: React.FC<{
   const { handlerOffset, index, children, visibleRanges, animationStyle } = props;
 
   const {
-    props: { loop, dataLength, width, height, vertical, customConfig, mode, modeConfig },
+    props: { loop, dataLength, width, height, vertical, customConfig, mode, modeConfig, style },
     common,
     layout: { updateItemDimensions },
   } = useGlobalState();
@@ -40,9 +41,11 @@ export const ItemLayout: React.FC<{
   });
 
   const fallbackSize = common.size;
-  // NOTE: `width`/`height` props are deprecated from v5 onwards. We still read them here so
-  // existing apps keep their layout until the props are fully removed.
-  const explicitAxisSize = vertical ? height : width;
+  // Prefer size from `style` (v5), then fallback to deprecated `width`/`height` for v4 compatibility.
+  const { width: styleWidth, height: styleHeight } = StyleSheet.flatten(style) || {};
+  const styleWidthNumber = typeof styleWidth === "number" ? styleWidth : undefined;
+  const styleHeightNumber = typeof styleHeight === "number" ? styleHeight : undefined;
+  const explicitAxisSize = vertical ? (styleHeightNumber ?? height) : (styleWidthNumber ?? width);
   const size = (explicitAxisSize ?? fallbackSize) || 0;
   const effectivePageSize = size > 0 ? size : undefined;
 
diff --git a/src/hooks/useCommonVariables.test.tsx b/src/hooks/useCommonVariables.test.tsx
@@ -229,18 +229,39 @@ describe("useCommonVariables", () => {
       expect(result.current.size).toBe(350);
     });
 
-    it("falls back to deprecated width prop when itemWidth not provided", () => {
+    it("prefers style.width over deprecated width prop when itemWidth not provided", () => {
       const props = createBaseProps({
         width: 500,
       });
       const { result } = renderHook(() => useCommonVariables(props));
 
+      expect(result.current.size).toBe(700);
+    });
+
+    it("prefers style.height over deprecated height prop when itemHeight not provided in vertical mode", () => {
+      const props = createBaseProps({
+        vertical: true,
+        height: 400,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(350);
+    });
+
+    it("falls back to deprecated width prop when style.width is not provided", () => {
+      const props = createBaseProps({
+        style: {},
+        width: 500,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
       expect(result.current.size).toBe(500);
     });
 
-    it("falls back to deprecated height prop when itemHeight not provided in vertical mode", () => {
+    it("falls back to deprecated height prop when style.height is not provided (vertical mode)", () => {
       const props = createBaseProps({
         vertical: true,
+        style: {},
         height: 400,
       });
       const { result } = renderHook(() => useCommonVariables(props));
diff --git a/src/hooks/useCommonVariables.ts b/src/hooks/useCommonVariables.ts
@@ -41,24 +41,29 @@ export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommo
       return explicitPageSize;
     }
 
+    const { width, height } = StyleSheet.flatten(style) || {};
+    const candidate = vertical ? height : width;
+    if (typeof candidate === "number" && candidate > 0) {
+      return candidate;
+    }
+
     // NOTE: `width`/`height` props are deprecated in v5. They are still respected here to
-    // maintain backwards compatibility with v4-style usage. Remove once the props are dropped.
+    // maintain backwards compatibility with v4-style usage. Prefer using `style` when both exist.
     const explicitCandidate = vertical ? explicitHeight : explicitWidth;
     if (typeof explicitCandidate === "number" && explicitCandidate > 0) {
       return explicitCandidate;
     }
 
-    const { width, height } = StyleSheet.flatten(style) || {};
-    const candidate = vertical ? height : width;
-    return typeof candidate === "number" && candidate > 0 ? candidate : null;
+    return null;
   }, [vertical, style, explicitWidth, explicitHeight, explicitItemHeight, explicitItemWidth]);
 
   const resolvedSize = useSharedValue<number | null>(manualSize);
   const sizePhase = useSharedValue<TCarouselSizePhase>(manualSize ? "ready" : "pending");
 
   const defaultHandlerOffsetValue = manualSize ? -Math.abs(defaultIndex * manualSize) : 0;
   const _handlerOffset = useSharedValue<number>(defaultHandlerOffsetValue);
-  const handlerOffset = defaultScrollOffsetValue ?? _handlerOffset;
+  // Prefer the newer `scrollOffsetValue` name, but keep the legacy prop for compatibility.
+  const handlerOffset = props.scrollOffsetValue ?? defaultScrollOffsetValue ?? _handlerOffset;
   const prevDataLength = useSharedValue(dataLength);
   const prevSize = useSharedValue(manualSize ?? 0);
   const sizeExplicit = React.useMemo(() => {
diff --git a/src/hooks/usePropsErrorBoundary.ts b/src/hooks/usePropsErrorBoundary.ts
diff --git a/src/types.ts b/src/types.ts
