feat!: Dynamic sizing with itemWidth/itemHeight props & modernized style API

[dohooo]

✨ Key Features

1. New itemWidth/itemHeight Props

• Control snapping behavior independently of container size
• Enable multiple items per viewport (e.g., show 3 cards at once)
• Useful for grid layouts and partial item displays

<Carousel
  style={{ width: 300 }}
  itemWidth={100}  // 3 items visible
/>

2. Modernized Style API

• style prop now controls outer container (positioning, dimensions, margins)
• New contentContainerStyle replaces containerStyle for scrollable content
• Deprecated direct width/height props in favor of style-based approach
• Added onLayout callback for container measurement events

💥 Breaking Changes

API Changes

• width/height props deprecated (use style instead)
• containerStyle renamed to contentContainerStyle
• onProgressChange no longer accepts SharedValue, only callback functions

📝 Migration Guide

// Before (v4)
<Carousel
  width={300}
  height={200}
  containerStyle={{ paddingHorizontal: 16 }}
/>

// After (v5)
<Carousel
  style={{ width: 300, height: 200 }}
  contentContainerStyle={{ paddingHorizontal: 16 }}
/>

// Dynamic sizing (new)
<Carousel style={{ flex: 1 }} />  // Auto-measures

// Multiple items (new)
<Carousel 
  style={{ width: 300 }}
  itemWidth={75}  // Show 4 items
/>

[changeset-bot]

🦋 Changeset detected

Latest commit: e423b50

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
react-native-reanimated-carousel	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
react-native-reanimated-carousel	Ready	Preview	Comment	Sep 30, 2025 11:33am

[dosubot]

Related Documentation

Checked 1 published document(s). No updates required.

^{How did I do? Any feedback?}  

[codecov]

Codecov Report

❌ Patch coverage is 62.79070% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.97%. Comparing base (5e6ec2a) to head (e423b50).

Files with missing lines	Patch %	Lines
src/components/ItemLayout.tsx	43.47%	7 Missing and 6 partials ⚠️
src/hooks/useCarouselController.tsx	60.86%	4 Missing and 5 partials ⚠️
src/hooks/usePropsErrorBoundary.ts	66.66%	2 Missing and 3 partials ⚠️
src/components/CarouselLayout.tsx	57.14%	0 Missing and 3 partials ⚠️
src/components/ScrollViewGesture.tsx	50.00%	0 Missing and 1 partial ⚠️
src/hooks/useCommonVariables.ts	90.90%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #853      +/-   ##
==========================================
+ Coverage   76.29%   76.97%   +0.68%     
==========================================
  Files          35       35              
  Lines         907      973      +66     
  Branches      286      324      +38     
==========================================
+ Hits          692      749      +57     
- Misses        128      138      +10     
+ Partials       87       86       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.