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[bot]]

🦋 Changeset detected

Latest commit: 19114925828b6e50aba65089081422553964aee0

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[bot]]

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	Dec 11, 2025 3:28pm

[dosubot[bot]]

Related Documentation

Checked 1 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[codecov[bot]]

Codecov Report

:x: Patch coverage is 67.41573% with 29 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 82.23%. Comparing base (5e6ec2a) to head (1911492). :warning: Report is 1 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #853      +/-   ##
==========================================
+ Coverage   76.29%   82.23%   +5.94%     
==========================================
  Files          35       35              
  Lines         907      974      +67     
  Branches      286      327      +41     
==========================================
+ Hits          692      801     +109     
+ Misses        128       79      -49     
- Partials       87       94       +7     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

[arekkubaczkowski]

looking forward for this one 🚀

[markwitt1]

What are the blockers here? For me the 5.0.0 beta is not working while this PR branch is. Is there any way to help get this released