Skip to content

README.md

Latest commit

 

History

History
222 lines (157 loc) · 7.84 KB

README.md

File metadata and controls

222 lines (157 loc) · 7.84 KB

React Native Hero Carousel - Example App

This example app demonstrates all the features and capabilities of the @strv/react-native-hero-carousel library. It's built with Expo and showcases various carousel implementations, from basic auto-scrolling carousels to advanced video carousels with custom animations.

🚀 Quick Start

Prerequisites

  • Node.js (v18 or higher)
  • yarn (recommended) or npm/pnpm
  • Expo CLI
  • iOS Simulator (macOS) or Android Emulator

Installation

  1. Install dependencies

    yarn install

  2. Start the development server

    yarn start

  3. Run on your preferred platform

    • iOS Simulator: Press i in the terminal or scan QR with Expo Go
    • Android Emulator: Press a in the terminal or scan QR with Expo Go
    • Physical Device: Install Expo Go and scan the QR code

📱 Available Examples

The app includes a comprehensive set of examples demonstrating different carousel use cases:

Core Examples

Example Features Best For
Basic Carousel Auto-scrolling, infinite loop, image preloading Simple hero sections, product showcases
Animated Carousel Custom transitions, scale/rotation effects, pagination Interactive galleries, feature highlights
Video Carousel Video playback, play/pause controls, duration sync Video showcases, tutorials, media content
Timer Pagination Custom intervals per slide, visual progress Announcements, promotional content
Entering Animation Advanced slide entrance effects Product launches, storytelling
Offset Example Custom slide spacing and positioning Card layouts, content previews

Pagination Components

Component Description Use Case
Basic Pagination Simple dot indicators Standard navigation indicators
Timer Pagination Animated progress bars Visual timing feedback

🎯 Key Features Demonstrated

🎬 Video Integration

  • Seamless video playback with expo-video
  • Auto-scroll synced with video duration
  • Play/pause controls with gesture support
  • Background video management

🎨 Custom Animations

  • Scale, rotation, and opacity transitions
  • Parallax effects using interpolateInsideCarousel
  • Entrance animations for slides
  • Smooth gesture-based navigation

⏱️ Timer Controls

  • Dynamic intervals per slide
  • Visual progress indicators
  • Pause/resume on user interaction
  • Custom timing functions

📊 Performance Optimization

  • Image preloading for smooth transitions
  • Memoized components for better performance
  • Efficient gesture handling
  • Worklet-based animations for 60fps

🛠️ Development

Project Structure

example/
├── app/                          # App router configuration
│   ├── (examples)/              # Example screens
│   │   ├── basic.tsx           # Basic carousel route
│   │   ├── animated.tsx        # Animated carousel route
│   │   ├── video-carousel.tsx  # Video carousel route
│   │   └── ...                 # Other example routes
│   └── _layout.tsx             # Root layout
├── examples/                    # Example implementations
│   ├── BasicExample.tsx        # Basic carousel implementation
│   ├── AnimatedExample.tsx     # Animated carousel with custom transitions
│   ├── VideoCarouselExample.tsx # Video carousel implementation
│   ├── components/             # Reusable example components
│   │   ├── Pagination.tsx      # Basic pagination component
│   │   └── TimerPagination.tsx # Timer pagination component
│   └── utils.ts               # Shared utilities
└── hooks/                      # Custom hooks for examples
    └── useActiveSlideEffect.ts # Hook for managing active slide effects

Adding New Examples

  1. Create the example component in examples/YourExample.tsx
  2. Add a route in app/(examples)/your-example.tsx
  3. Update the navigation in app/(examples)/_layout.tsx
  4. Test on multiple platforms (iOS, Android, Web)

Example template:

// examples/YourExample.tsx
import { HeroCarousel, CarouselContextProvider } from '@strv/react-native-hero-carousel'

export default function YourExample() {
  return (
    <CarouselContextProvider interval={3000} disableAutoScroll={false} initialIndex={0}>
      <HeroCarousel>{/* Your slides */}</HeroCarousel>
    </CarouselContextProvider>
  )
}

Custom Hooks

The example app includes custom hooks that you can reference:

  • useActiveSlideEffect - Manage side effects when slides become active/inactive
  • useIsActiveSlide - Determine if the current slide is active
  • useColorScheme - Handle light/dark theme switching

🧪 Testing

Manual Testing Checklist

  • Smooth scrolling on all platforms
  • Auto-scroll timing is consistent
  • User interaction properly pauses auto-scroll
  • Video playback works correctly
  • Pagination indicators update in real-time
  • Performance is smooth (60fps animations)
  • Memory usage is reasonable (no leaks)

Performance Testing

  1. Profile with Flipper - Monitor frame rates and memory usage
  2. Test on low-end devices - Ensure smooth performance
  3. Memory profiling - Check for memory leaks with video content

🚨 Troubleshooting

Common Issues

Metro bundler issues:

yarn start --clear-cache

iOS build issues:

cd ios && pod install && cd ..

Android build issues:

yarn android --clear

Video not playing:

  • Check network connection
  • Verify video URLs are accessible
  • Ensure expo-video is properly configured

Performance Issues

  • Reduce image sizes if scrolling is choppy
  • Enable Hermes for better JavaScript performance
  • Use development builds instead of Expo Go for better performance
  • Profile with React DevTools to identify bottlenecks

📚 Learn More

Library Documentation

Expo Resources

🤝 Contributing

Found a bug or want to add a new example? Contributions are welcome!

  1. Fork the repository
  2. Create a feature branch
  3. Add your example or fix
  4. Test on multiple platforms
  5. Submit a pull request

📄 License

This example app is part of the @strv/react-native-hero-carousel library and is licensed under the MIT License.

Made with ❤️ by STRV 🚀