Patch Changes

• #891 73d066d Thanks @notsuhas! - - Fix non-loop scrollTo() so backward jumps keep the correct negative offset instead of briefly rendering a blank frame.
  • Add regression tests for non-loop backward scrollTo() and returning to index 0.

Patch Changes

• #883 dd4e867 Thanks @dohooo! - Fix four high-confidence issues with TDD-first coverage:

  • Issue #837: Fix non-loop + overscrollEnabled={false} behavior so right overdrag is clamped instead of bouncing past bounds.
  • Issue #855: Harden visible range calculation for invalid runtime sizes (for example, viewSize becoming NaN) to avoid blank rendering in non-loop scenarios.
  • Issue #863: Improve Pagination accessibility defaults and add paginationItemAccessibility overrides for Pagination.Basic and Pagination.Custom.
  • Issue #867: Guard customAnimation output by sanitizing style values and normalizing zIndex to finite integers to reduce native crash risk.

  Also adds focused regression tests for gesture translation clamping, visibility range fallbacks, pagination accessibility labels, and animation style sanitization.

Patch Changes

• #878 79ae0e6 Thanks @dohooo! - # Fix gesture blocking when using flex-based sizing

  Bug Fixes

  Gesture Blocking with flex: 1

  Fixed an issue where gestures were blocked or delayed when using style={{ flex: 1 }} instead of explicit width/height props.

  Root Cause: Race condition between sizeReady (SharedValue, updates immediately on UI thread) and size (React state, updates asynchronously). When sizeReady became true, the React state size was still 0, causing gesture handlers to incorrectly block input.

  Solution: All worklet functions now use resolvedSize.value (SharedValue) instead of React state size to ensure consistent synchronization on the UI thread.

  itemWidth/itemHeight Not Working

  Fixed an issue where itemWidth/itemHeight props were being ignored - items rendered at container width instead of the specified item dimensions.

  Root Cause: ItemLayout.tsx was prioritizing style.width over itemWidth prop.

  Solution: Now correctly prioritizes explicit itemWidth/itemHeight props for item sizing.

  Affected Files

  • src/components/ScrollViewGesture.tsx - Fixed race condition in gesture handlers
  • src/components/ItemLayout.tsx - Fixed itemWidth/itemHeight priority

• #875 13861ac Thanks @dohooo! - Fix web documentation examples crash by upgrading react-native-worklets from 0.5.1 to 0.5.2. This resolves the "createSerializableObject should never be called in JSWorklets" error that occurred on web platform.

Minor Changes

• #873 ffb59aa Thanks @dohooo! - # 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):

  <Carousel width={300} height={200} />

  After (v5 style):

  <Carousel style={{ width: 300, height: 200 }} />

  Scroll offset:

  // 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

Minor Changes

• #853 c595958 Thanks @dohooo! - - 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

• #853 c595958 Thanks @dohooo! - ## ✨ 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

  // 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.

Patch Changes

• #872 12c1a63 Thanks @dohooo! - Clamp visible ranges for non-loop overdrag and add test to ensure the first item stays visible when dragging right on the first page. Credits to PR #869 reporter.

• #871 bc7daaf Thanks @dohooo! - Fix non-loop overscroll direction so tiny positive offsets at the first page no longer wrap to the last page when calling next()/scrollTo(), and add integration coverage for the scenario. Thanks to @hennessyevan for the original report and PR 839 inspiration.

• #866 566bf52 Thanks @hennessyevan! - Fix pagination accessibility state by syncing selection with scheduleOnRN instead of reading reanimated values during render, and add coverage to avoid test warnings.

Major Changes

• #850 9b388e6 Thanks @dohooo!

• 🎯 Support for Expo 54 & Dynamic Sizing

  ✨ Major Features

  Dynamic Sizing Support

  • Auto-sizing: width and height props are now optional. Carousel automatically measures container dimensions via layout

  Expo 54 Compatibility

  • Full support for Expo SDK 54
  • Updated dependencies for latest React Native ecosystem

  💥 Breaking Changes

  Dependencies Update Required

  • react-native-reanimated: Upgrade to ^4.1.0 (was ^3.0.0)
  • react-native-worklets: New peer dependency ^0.5.1 required
  • react-native-gesture-handler: Minimum version ^2.9.0 (no breaking changes)

  Migration Steps

  1. Upgrade Reanimated: npm install react-native-reanimated@^4.1.0
  2. Install Worklets: npm install react-native-worklets@^0.5.1
  3. Follow Reanimated 4.0 migration guide for any breaking changes

  🔧 Technical Improvements

  • Replaced deprecated runOnJS with scheduleOnRN from react-native-worklets
  • Enhanced test coverage for dynamic sizing scenarios
  • Improved overscroll protection logic
  • Better error handling for edge cases

  📚 Documentation

  • Updated installation guide with new dependency requirements
  • Added migration guide from v4 to v5
  • Enhanced examples showcasing dynamic sizing capabilities

  Fixes: #668 - Auto height calculation support

Patch Changes

• #834 1d2767b Thanks @dohooo! - Add accessibility support to pagination components and replace deprecated TouchableWithoutFeedback with Pressable

  • Add comprehensive accessibility props (accessibilityLabel, accessibilityRole, accessibilityHint, accessibilityState) to both Basic and Custom pagination components
  • Add carouselName prop to allow descriptive accessibility labels
  • Replace TouchableWithoutFeedback with Pressable to remove deprecation warnings
  • Improve screen reader support with proper labeling and state information

  Co-authored-by: AlexJackson01 alex@example.com

• #834 1d2767b Thanks @dohooo! - Add comprehensive programmatic control documentation

  • Add new "Programmatic Control" documentation page with detailed examples
  • Clarify that there's no React-style controlled component mode
  • Update migration guide to use correct terminology and link to new docs
  • Provide examples for common use cases: pagination, navigation buttons, dynamic content, auto-advance, and jump-to-item patterns
  • Include warnings about race conditions and timing considerations

• #834 1d2767b Thanks @dohooo! - Replace deprecated TouchableWithoutFeedback with Pressable in pagination components

  Fixes deprecation warnings by replacing TouchableWithoutFeedback with the recommended Pressable component in both Basic and Custom pagination items. This change maintains the same functionality while using the modern React Native API.

  Closes #812

• #834 1d2767b Thanks @dohooo! - Update homepage in package.json

Patch Changes

• 2b91b7e Thanks @dohooo! - change width breaking the pagination component

Patch Changes

• 8bfb7b1 Thanks @dohooo! - Configure Babel for React Native Reanimated build

Major Changes

• #444 56e20c8 Thanks @dohooo! - feat: use new RNGH api

  Updates react-native-gesture-handler to >=2.9.0 and replaces usage of useAnimatedGestureHandler with the new gesture handler API which supports the new gesture handler web implementation.

Minor Changes

• #507 c6d58e5 Thanks @dohooo! - Support to fix the scroll direction through new API, fixedDirection.

Patch Changes

• #687 55c55ff Thanks @dohooo! - feat: Add containerStyle prop to control the container styles.

• d5de105 Thanks @dohooo! - Added missing dependencies for web to work

• #507 353fdce Thanks @dohooo! - remove postinstall script.

• #666 2982fcd Thanks @dohooo! - fix: typescript error where MeasuredDimension can be null

• #677 00c948b Thanks @nmassey! - fix Pagination.Basic and Pagination.Custom usage of TouchableWithoutFeedback.
  This fixes press event handler not working correctly. (Thanks to @qwertychouskie for reporting!)

• #672 5fa78a7 Thanks @dohooo! - revert autoPlay changes

• #600 d9557b2 Thanks @dohooo! - Fixed an issue where endWithSpring used outdated data from useSharedValue after onGestureEnd, causing incorrect carousel behavior on direction reversal.

• 85f24e7 Thanks @dohooo! - Type error property push does not exist on type

• #517 9f3a3d6 Thanks @dohooo! - Reduce the amount of work done when rendering data.

• #496 fdeef6b Thanks @dohooo! - re-calculate when window size changed in browser.

• #597 0d2b930 Thanks @dohooo! - Adds Pagination Component

• #666 32c8c36 Thanks @dohooo! - Add <Pagination.Custom/> dot animation.

• #498 096ac75 Thanks @dohooo! - re-calculate when window size changed in browser. (re-bump for alpha.3)

• #577 17621ca Thanks @nmassey! - fix: make gesture onStart/onUpdate/onEnd (et al) callbacks run as worklets again

• #733 3040863 Thanks @dohooo! - Add pointerEvents: ‘box-none’ to ItemLayout component to allow touches for children components outside item boundaries

• #494 6b849ec Thanks @dohooo! - Removed the reset logic when user change the defaultIndex prop. (We couldn't update the handlerOffset value when user change the defaultIndex. Because the carousel component already be a non-controlled component. So the subsequent changes of defaultIndex will be ignored.)

• #735 848f458 Thanks @dohooo! - This PR updates the customAnimation function signature to include an index parameter, allowing users to apply custom animations based on the item’s index.

• #648 0abdb2d Thanks @nmassey! - fix app crash when using "onProgressChange" prop as function

• #721 2a8111e Thanks @dohooo! - fix: parallax layout with new arch enabled

• #492 978b59f Thanks @dohooo! - feat: change the way of PanGestureHandler modification from panGestureHandlerProps to onConfigurePanGesture.

  e.g.

  <Carousel
    onConfigurePanGesture={(gestureChain) => {
      gestureChain.activeOffsetX([-10, 10]);
    }}
  />

• #528 139d5e5 Thanks @dohooo! - Exported TAnimationStyle types.

• #710 d98bb99 Thanks @nmassey! - fix: remove shared value access warning from react-native-reanimated

• #510 b3cc591 Thanks @dohooo! - Support to specific direction to auto play.

• #703 564d2f5 Thanks @dohooo! - Update homepage in package.json

• #528 b654f43 Thanks @dohooo! - Replaced 'onScrollBegin' with 'onScrollStart' to better match gesture callback.

• 618d90d Thanks @dohooo! - Loss of precision during arithmetic conversion

• #576 a99f069 Thanks @nmassey! - fix: rework code to avoid possible flicker when starting pan (panOffset race condition)

• #724 33022e6 Thanks @dohooo! - fix: next item function overscolling with overscro...