Usage#
Here is a simple usage of the React Native Reanimated Carousel. For more scrollable usage please read Scrollables.
<video width="320" height="240" autoPlay loop style={{border:'1px solid gray', margin:"0 auto",borderRadius:10,marginTop:10}}>
import * as React from "react";
import { Dimensions, Text, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { useSharedValue } from "react-native-reanimated";
import Carousel, {
ICarouselInstance,
Pagination,
} from "react-native-reanimated-carousel";
const data = [...new Array(6).keys()];
const width = Dimensions.get("window").width;
function App() {
const ref = React.useRef<ICarouselInstance>(null);
const progress = useSharedValue<number>(0);
const onPressPagination = (index: number) => {
ref.current?.scrollTo({
/**
* Calculate the difference between the current index and the target index
* to ensure that the carousel scrolls to the nearest index
*/
count: index - progress.value,
animated: true,
});
};
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<Carousel
ref={ref}
style={{ width, height: width / 2 }}
data={data}
onProgressChange={progress}
renderItem={({ index }) => (
<View
style={{
flex: 1,
borderWidth: 1,
justifyContent: "center",
}}
<Text style={{ textAlign: "center", fontSize: 30 }}>{index}</Text>
</View>
)}
/>
<Pagination.Basic
progress={progress}
data={data}
dotStyle={{ backgroundColor: "rgba(0,0,0,0.2)", borderRadius: 50 }}
containerStyle={{ gap: 5, marginTop: 10 }}
onPress={onPressPagination}
carouselName="Main carousel"
/>
</GestureHandlerRootView>
);
}
export default App;
### Accessible Pagination
`Pagination.Basic` and `Pagination.Custom` announce each item as a button by default. Set `carouselName` to add context to the default label, or use `paginationItemAccessibility` when you need custom or localized announcements:
```tsx
<Pagination.Basic
progress={progress}
data={data}
onPress={onPressPagination}
carouselName="Featured products"
paginationItemAccessibility={(index, length) => ({
accessibilityLabel: `Product ${index + 1} of ${length}`,
accessibilityHint: `Go to product ${index + 1}`,
})}
/>
Sizing Your Carousel#
The Carousel component supports multiple ways to define its size. Understanding these options helps you achieve the layout you need.
1. Explicit Dimensions (Recommended)#
The most straightforward approach is setting explicit width and height via the style prop:
<Carousel
style={{ width: 300, height: 200 }}
data={data}
renderItem={renderItem}
/>
This gives you full control over the carousel's dimensions and is the most predictable approach.
2. Flex-based Sizing#
You can use flex layout to have the carousel fill its parent container:
<View style={{ flex: 1 }}>
<Carousel
style={{ flex: 1 }}
data={data}
renderItem={renderItem}
/>
</View>
The carousel will measure its container and adapt automatically. This is useful when you want the carousel to respond to its parent's layout.
3. Custom Snap Distance with itemWidth / itemHeight#
When you want items smaller than the container with custom snapping behavior, use itemWidth (horizontal) or itemHeight (vertical):
// Container is 400px wide, but snaps every 200px (showing ~2 items)
<Carousel
style={{ width: 400, height: 200 }}
itemWidth={200}
data={data}
renderItem={renderItem}
/>
This is particularly useful for:
- Showing multiple items at once
- Implementing "peek" effects where adjacent items are partially visible
- Custom snap intervals independent of container size
4. Legacy Props (Deprecated)#
The width and height props are deprecated but still supported for backward compatibility:
// Deprecated - use style={{ width, height }} instead
<Carousel
width={300}
height={200}
data={data}
renderItem={renderItem}
/>
We recommend migrating to the style prop for new code.
Sizing Summary#
| Scenario | Props to Use | Example |
|---|---|---|
| Fixed size | style={{ width, height }} | style={{ width: 300, height: 200 }} |
| Fill parent | style={{ flex: 1 }} | Parent must have defined size |
| Custom snap | style + itemWidth/itemHeight | style={{ width: 400 }} itemWidth={200} |
| Vertical | style + vertical | style={{ height: 400 }} vertical |
Important Notes#
-
At least one dimension is required: The carousel needs to know its size either through explicit dimensions, flex layout, or legacy props.
-
For horizontal carousels: Width is the primary dimension that controls snapping.
-
For vertical carousels: Height is the primary dimension that controls snapping.
-
Performance: The carousel waits for layout measurement before rendering items. With
style={{ flex: 1 }}, there may be a brief moment before items appear as the component measures its container.