diff --git a/README.md b/README.md index b6a5b9e..7db65a6 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A highly customizable, performant carousel component for React Native with advanced animations, auto-scrolling capabilities, and infinite scrolling support. Built with React Native Reanimated for smooth, native-level performance. +**✨ Context-Based Configuration** - All carousel settings are configured through the context provider for a clean, centralized API. + ## Features ✨ **Auto-scrolling** with customizable intervals @@ -55,7 +57,7 @@ const Slide = ({ title, color }: { title: string; color: string }) => ( export default function BasicCarousel() { return ( - + {slides.map((slide) => ( @@ -90,38 +92,50 @@ const styles = StyleSheet.create({ #### `CarouselContextProvider` -The context provider that must wrap your carousel components. +The context provider that must wrap your carousel components. **All carousel configuration is passed here.** ```tsx withTiming(to, { duration })} // Custom animation > {children} ``` +**Props:** + +| Prop | Type | Default | Description | +| ----------------------- | ------------------------------------------ | ------------ | ----------------------------------------------------------------------------------- | +| `initialIndex` | `number` | `0` | Initial slide index to start from | +| `slideWidth` | `number` | screen width | Width of each slide in pixels | +| `interval` | `number \| ((index: number) => number)` | `3000` | Auto-scroll interval in milliseconds, or function returning interval for each slide | +| `disableAutoScroll` | `boolean` | `false` | Disable automatic scrolling | +| `disableInfiniteScroll` | `boolean` | `false` | Disable infinite scrolling (shows first/last slide boundaries) | +| `autoScrollAnimation` | `(to: number, duration: number) => number` | `withTiming` | Custom animation function for auto-scroll transitions | +| `children` | `React.ReactNode` | Required | Carousel content (should contain HeroCarousel component) | + #### `HeroCarousel` -The main carousel component with auto-scrolling functionality. +The main carousel component that renders slides. **Takes no configuration props** - all configuration is handled by the context. ```tsx - withTiming(to, { duration })} // Custom page transition animation -> - {children} + + {slides.map((slide) => ( + + ))} ``` **Props:** -| Prop | Type | Default | Description | -| ------------------- | --------------------------------------- | -------- | ----------------------------------------------------------------------------------- | --- | -| `interval` | `number \| ((index: number) => number)` | `3000` | Auto-scroll interval in milliseconds, or function returning interval for each slide | -| `disableAutoScroll` | `boolean` | `false` | Disable automatic scrolling | | -| `children` | `React.ReactNode[]` | Required | Array of slide components | +| Prop | Type | Description | +| ---------- | ------------------- | ------------------------- | +| `children` | `React.ReactNode[]` | Array of slide components | ### Hooks @@ -147,7 +161,7 @@ const { scrollValue, timeoutValue, slideWidth, userInteracted, setUserInteracted Get the current slide information and auto-scroll controls. ```tsx -const { index, total, runAutoScroll, goToPage } = useAutoCarouselSlideIndex() +const { index, total, runAutoScroll, goToPage } = useHeroCarouselSlideIndex() ``` **Returns:** @@ -232,32 +246,68 @@ All pagination components automatically sync with the carousel state and support ## Advanced Usage +### Configuration Examples + +Different carousel configurations using the context provider: + +```tsx +// Basic auto-scrolling carousel + + {slides} + + +// Video carousel without auto-scroll + + {videoSlides} + + +// Carousel with custom intervals per slide + (index + 1) * 2000}> + {slides} + + +// Carousel starting from specific slide + + {slides} + + +// Custom slide width and animation + withSpring(to, { damping: 15 })} +> + {slides} + +``` + ### Programmatic Navigation Control the carousel programmatically using the context: ```tsx const CarouselWithControls = () => { - const { scrollValue } = useCarouselContext() - const { runAutoScroll } = useAutoCarouselSlideIndex() + const { scrollValue, goToPage } = useCarouselContext() + const { runAutoScroll } = useHeroCarouselSlideIndex() const goToNext = () => { runAutoScroll(0) // Immediate transition } const goToSlide = (slideIndex: number) => { - scrollValue.value = withTiming(slideIndex, { duration: 500 }) + goToPage(slideIndex, 500) // Go to slide with 500ms animation } return ( - - {/* Your slides */} - - -