React Native Hero Carousel

Features

Installation

npm install @strv/react-native-hero-carousel
# or
yarn add @strv/react-native-hero-carousel
# or
pnpm add @strv/react-native-hero-carousel

Peer Dependencies

npm install react-native-reanimated react-native-gesture-handler

Quick Start

import React from 'react'
import { View, Text, StyleSheet } from 'react-native'
import { HeroCarousel } from '@strv/react-native-hero-carousel'
const slides = [
 { id: 1, title: 'Slide 1', color: '#FF6B6B' },
 { id: 2, title: 'Slide 2', color: '#4ECDC4' },
 { id: 3, title: 'Slide 3', color: '#45B7D1' },
 { id: 4, title: 'Slide 4', color: '#96CEB4' },
]
const Slide = ({ title, color }: { title: string; color: string }) => (
 <View style={[styles.slide, { backgroundColor: color }]}>
 <Text style={styles.title}>{title}</Text>
 </View>
)
export default function BasicCarousel() {
 return (
 <HeroCarousel.Provider interval={4000} disableAutoScroll={false} initialIndex={0}>
 <View style={styles.container}>
 <HeroCarousel>
 {slides.map((slide) => (
 <Slide key={slide.id} title={slide.title} color={slide.color} />
 ))}
 </HeroCarousel>
 </View>
 </HeroCarousel.Provider>
 )
}
const styles = StyleSheet.create({
 container: {
 flex: 1,
 },
 slide: {
 flex: 1,
 justifyContent: 'center',
 alignItems: 'center',
 },
 title: {
 fontSize: 24,
 fontWeight: 'bold',
 color: 'white',
 },
})

API Reference

Components

<HeroCarousel.Provider>
 <HeroCarousel>
 <HeroCarousel.Item>{/* Your slide content */}</HeroCarousel.Item>
 </HeroCarousel>
</HeroCarousel.Provider>

HeroCarousel.Provider

<HeroCarousel.Provider
 initialIndex={0} // Initial slide index (default: 0)
 slideWidth={screenWidth} // Width of each slide (default: screen width)
 interval={3000} // Auto-scroll interval in ms
 disableAutoScroll={false} // Disable auto-scrolling
 disableInfiniteScroll={false} // Disable infinite scrolling
 autoScrollAnimation={(to, duration) => withTiming(to, { duration })} // Custom animation
>
 {children}
</HeroCarousel.Provider>

HeroCarousel

<HeroCarousel>
 {slides.map((slide) => (
 <YourSlideComponent key={slide.id} {...slide} />
 ))}
</HeroCarousel>

HeroCarousel.Item

<HeroCarousel.Item>{/* Your slide content */}</HeroCarousel.Item>

HeroCarousel.AnimatedView

import { FadeIn, FadeOut } from 'react-native-reanimated'
;<HeroCarousel.AnimatedView
 entering={FadeIn.duration(400)}
 exiting={FadeOut.duration(300)}
 style={styles.animatedContent}
>
 <Text>This animates when the slide becomes active</Text>
</HeroCarousel.AnimatedView>

Hooks

useCarouselContext()

const { scrollValue, timeoutValue, slideWidth, userInteracted, setUserInteracted } =
 useCarouselContext()

useAutoCarouselSlideIndex()

const { index, total, runAutoScroll, goToPage } = useAutoCarouselSlideIndex()

useInterpolateInsideCarousel()

import { useInterpolateInsideCarousel } from '@strv/react-native-hero-carousel'
import Animated, { useAnimatedStyle, interpolate, Extrapolation } from 'react-native-reanimated'
const Slide = () => {
 const progress = useInterpolateInsideCarousel({
 valueBefore: 0, // Value for slides before current
 thisValue: 1, // Value for current slide
 valueAfter: 0, // Value for slides after current
 offset: 0.2, // Animation offset (optional)
 })
 const animatedStyle = useAnimatedStyle(() => {
 return {
 opacity: progress.value,
 transform: [
 {
 scale: interpolate(progress.value, [0, 1], [0.8, 1], Extrapolation.CLAMP),
 },
 ],
 }
 })
 return <Animated.View style={animatedStyle}>{/* Your content */}</Animated.View>
}

Examples

🏃‍♂️ Running the Example App

cd example
yarn install
yarn start

📱 Available Examples

🎯 Key Example Features

📍 Pagination Examples

Advanced Usage

Configuration Examples

// Basic auto-scrolling carousel
<HeroCarousel.Provider interval={3000}>
 <HeroCarousel>{slides}</HeroCarousel>
</HeroCarousel.Provider>
// Video carousel without auto-scroll
<HeroCarousel.Provider disableAutoScroll>
 <HeroCarousel>{videoSlides}</HeroCarousel>
</HeroCarousel.Provider>
// Carousel with custom intervals per slide
<HeroCarousel.Provider interval={(index) => (index + 1) * 2000}>
 <HeroCarousel>{slides}</HeroCarousel>
</HeroCarousel.Provider>
// Carousel starting from specific slide
<HeroCarousel.Provider initialIndex={2} disableInfiniteScroll>
 <HeroCarousel>{slides}</HeroCarousel>
</HeroCarousel.Provider>

// Custom slide width and animation
<HeroCarousel.Provider
 slideWidth={300}
 autoScrollAnimation={(to, duration) => withSpring(to, { damping: 15 })}
>
 <HeroCarousel>{slides}</HeroCarousel>
</HeroCarousel.Provider>

Using HeroCarousel.AnimatedView

import { HeroCarousel } from '@strv/react-native-hero-carousel'
import { FadeIn, FadeOut, SlideInDown } from 'react-native-reanimated'
const Slide = ({ title, image }: { title: string; image: string }) => (
 <View style={styles.slide}>
 <Image source={{ uri: image }} style={styles.image} />
 {/* Content that animates when slide becomes active */}
 <HeroCarousel.AnimatedView
 entering={FadeIn.duration(400)}
 exiting={FadeOut.duration(300)}
 style={styles.content}
 >
 <Text style={styles.title}>{title}</Text>
 </HeroCarousel.AnimatedView>
 {/* Multiple animated views with different timings */}
 <HeroCarousel.AnimatedView
 entering={SlideInDown.duration(500).delay(200)}
 style={styles.subtitle}
 >
 <Text>Subtitle with delay</Text>
 </HeroCarousel.AnimatedView>
 </View>
)
// Usage
<HeroCarousel.Provider>
 <HeroCarousel>
 {slides.map((slide) => (
 <Slide key={slide.id} {...slide} />
 ))}
 </HeroCarousel>
</HeroCarousel.Provider>

Programmatic Navigation

const CarouselWithControls = () => {
 const { scrollValue, goToPage } = useCarouselContext()
 const { runAutoScroll } = useAutoCarouselSlideIndex()
 const goToNext = () => {
 runAutoScroll(0) // Immediate transition
 }
 const goToSlide = (slideIndex: number) => {
 goToPage(slideIndex, 500) // Go to slide with 500ms animation
 }
 return (
 <HeroCarousel.Provider disableAutoScroll>
 <View>
 <HeroCarousel>{/* Your slides */}</HeroCarousel>
 <View style={styles.controls}>
 <Button title="Previous" onPress={() => goToSlide(scrollValue.value - 1)} />
 <Button title="Next" onPress={goToNext} />
 </View>
 </View>
 </HeroCarousel.Provider>
 )
}

Performance Tips

// Good: Memoized slide component
const SlideComponent = React.memo(({ data }) => {
 // Your slide content
})
// Good: Preload images
useEffect(() => {
 images.forEach((uri) => Image.prefetch(uri))
}, [])

Architecture

Compound Pattern

<HeroCarousel.Provider>
 <HeroCarousel>
 <HeroCarousel.Item>
 <HeroCarousel.AnimatedView>{/* Your content */}</HeroCarousel.AnimatedView>
 </HeroCarousel.Item>
 </HeroCarousel>
</HeroCarousel.Provider>

Context-Based Configuration

Troubleshooting

Common Issues

Contributing

License

Credits