npm package: @mahbub_ali/carousel
Description: A comprehensive carousel package for React Native with multiple carousel types - horizontal, vertical, parallax, stack, infinite loop, multi-item, banner, thumbnail, and animated carousels
Author: Mahbub Ali
Latest version: 1.0.1

# @mahbub_ali/carousel

A comprehensive carousel package for React Native with multiple carousel types.

## Installation

```bash
npm install @mahbub_ali/carousel
# or
yarn add @mahbub_ali/carousel
```

### Peer Dependencies

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

For Expo projects:

```bash
npx expo install react-native-reanimated react-native-gesture-handler
```

## Features

- ✅ 23+ Different Carousel Types
- ✅ Horizontal & Vertical Support
- ✅ Auto-play & Loop
- ✅ Smooth Animations
- ✅ Fully Customizable
- ✅ Easy to Use API
- ✅ Multiple Animation Effects
- ✅ Built-in Pagination & Progress Indicators

## Carousel Types

### Basic Carousels

1. **BasicHorizontal** - Basic horizontal carousel
2. **Vertical** - Vertical scrolling carousel
3. **Banner** - Full-width banner carousel
4. **InfiniteLoop** - Infinite loop carousel
5. **MultiItem** - Multiple items visible carousel

### Effect Carousels

6. **Parallax** - Parallax effect carousel
7. **Fade** - Fade transition carousel
8. **Scale** - Scale animation carousel
9. **Rotate** - Rotate animation carousel
10. **Zoom** - Zoom in/out effect carousel
11. **Flip** - 3D flip animation carousel
12. **Cube** - 3D cube rotation carousel
13. **Coverflow** - Coverflow style carousel

### Stack Carousels

14. **Stack** - Stacked card carousel
15. **HorizontalStack** - Horizontal stacked cards
16. **VerticalStack** - Vertical stacked cards
17. **CardDeck** - Card deck style carousel
18. **Accordion** - Accordion style carousel

### Special Carousels

19. **Thumbnail** - Main image with thumbnail strip
20. **Gallery** - Gallery with counter
21. **Tinder** - Tinder-style swipeable carousel
22. **Swipeable** - Enhanced swipeable carousel
23. **Wheel** - Wheel rotation carousel
24. **Animated** - Custom animated carousel

### With Indicators

25. **PaginationDots** - Carousel with pagination dots
26. **ProgressBar** - Carousel with progress bar

## Usage

### Sample Data Setup

```javascript
const data = [
  { 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: "#FFA07A" },
];

const renderSlide = ({ item }) => (
  <View
    style={{
      backgroundColor: item.color,
      flex: 1,
      justifyContent: "center",
      alignItems: "center",
      borderRadius: 20,
    }}
  >
    <Text style={{ fontSize: 32, fontWeight: "bold", color: "#fff" }}>
      {item.title}
    </Text>
  </View>
);
```

---

## Basic Carousels

### 1. BasicHorizontal

The most basic horizontal carousel - swipe to navigate between items.

```javascript
import { BasicHorizontal } from "@mahbub_ali/carousel";

<BasicHorizontal
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  loop={true}
  height={300}
/>;
```

### 2. Vertical

Vertical scrolling carousel - scroll up and down to navigate.

```javascript
import { Vertical } from "@mahbub_ali/carousel";

<Vertical
  data={data}
  renderItem={renderSlide}
  height={400}
  autoPlay={true}
  loop={true}
/>;
```

### 3. Banner

Full-width banner carousel - perfect for hero sections or promotional banners.

```javascript
import { Banner } from "@mahbub_ali/carousel";

<Banner
  data={data}
  renderItem={renderSlide}
  height={250}
  autoPlay={true}
  autoPlayInterval={2500}
/>;
```

### 4. InfiniteLoop

Endless scrolling carousel - seamlessly loops from end to beginning.

```javascript
import { InfiniteLoop } from "@mahbub_ali/carousel";

<InfiniteLoop
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  autoPlayInterval={1500}
  scrollAnimationDuration={1000}
/>;
```

### 5. MultiItem

Shows multiple items at once - with partial views of adjacent items.

```javascript
import { MultiItem } from "@mahbub_ali/carousel";

<MultiItem
  data={data}
  renderItem={renderSlide}
  width={280}
  height={250}
  autoPlay={false}
/>;
```

---

## Effect Carousels

### 6. Parallax

Parallax scrolling effect - background items move slower creating depth.

```javascript
import { Parallax } from "@mahbub_ali/carousel";

<Parallax
  data={data}
  renderItem={renderSlide}
  parallaxScrollingScale={0.9}
  parallaxScrollingOffset={50}
  autoPlay={true}
/>;
```

### 7. Fade

Fade in/out transition effect - smooth fade animation between items.

```javascript
import { Fade } from "@mahbub_ali/carousel";

<Fade
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  autoPlayInterval={3000}
/>;
```

### 8. Scale

Scale animation - items zoom in/out during transitions.

```javascript
import { Scale } from "@mahbub_ali/carousel";

<Scale
  data={data}
  renderItem={renderSlide}
  width={320}
  height={300}
  autoPlay={false}
/>;
```

### 9. Rotate

Rotate animation - items rotate during transitions.

```javascript
import { Rotate } from "@mahbub_ali/carousel";

<Rotate
  data={data}
  renderItem={renderSlide}
  width={320}
  height={300}
  autoPlay={false}
/>;
```

### 10. Zoom

Zoom in/out effect - center item stays zoomed.

```javascript
import { Zoom } from "@mahbub_ali/carousel";

<Zoom
  data={data}
  renderItem={renderSlide}
  width={360}
  height={300}
  autoPlay={false}
/>;
```

### 11. Flip

3D flip animation - card flip effect like flipping a card.

```javascript
import { Flip } from "@mahbub_ali/carousel";

<Flip
  data={data}
  renderItem={renderSlide}
  width={320}
  height={300}
  autoPlay={false}
/>;
```

### 12. Cube

3D cube rotation - rotates like a cube in 3D space.

```javascript
import { Cube } from "@mahbub_ali/carousel";

<Cube
  data={data}
  renderItem={renderSlide}
  width={320}
  height={300}
  autoPlay={false}
/>;
```

### 13. Coverflow

Coverflow style - iOS coverflow-like effect with perspective.

```javascript
import { Coverflow } from "@mahbub_ali/carousel";

<Coverflow
  data={data}
  renderItem={renderSlide}
  width={320}
  height={300}
  autoPlay={false}
/>;
```

---

## Stack Carousels

### 14. Stack

Stacked card carousel - cards displayed in a stack format.

```javascript
import { Stack } from "@mahbub_ali/carousel";

<Stack
  data={data}
  renderItem={renderSlide}
  width={300}
  height={400}
  loop={true}
/>;
```

### 15. HorizontalStack

Stacked cards in horizontal direction.

```javascript
import { HorizontalStack } from "@mahbub_ali/carousel";

<HorizontalStack
  data={data}
  renderItem={renderSlide}
  width={300}
  height={350}
  autoPlay={false}
/>;
```

### 16. VerticalStack

Stacked cards in vertical direction.

```javascript
import { VerticalStack } from "@mahbub_ali/carousel";

<VerticalStack
  data={data}
  renderItem={renderSlide}
  height={400}
  autoPlay={false}
/>;
```

### 17. CardDeck

Card deck style - stacked like playing cards.

```javascript
import { CardDeck } from "@mahbub_ali/carousel";

<CardDeck
  data={data}
  renderItem={renderSlide}
  width={340}
  height={400}
  autoPlay={false}
/>;
```

### 18. Accordion

Accordion style - expand/collapse effect.

```javascript
import { Accordion } from "@mahbub_ali/carousel";

<Accordion data={data} renderItem={renderSlide} height={300} loop={false} />;
```

---

## Special Carousels

### 19. Thumbnail

Main image with thumbnail strip below - click thumbnails to navigate.

```javascript
import { Thumbnail } from "@mahbub_ali/carousel";

<Thumbnail
  data={data}
  renderItem={renderSlide}
  renderThumbnail={(item, index) => (
    <View
      style={{
        backgroundColor: item.color,
        flex: 1,
        borderRadius: 8,
        justifyContent: "center",
        alignItems: "center",
      }}
    >
      <Text style={{ color: "#fff", fontWeight: "bold" }}>{index + 1}</Text>
    </View>
  )}
  thumbnailSize={60}
  thumbnailSpacing={10}
/>;
```

### 20. Gallery

Gallery carousel with counter - shows counter in bottom-right corner.

```javascript
import { Gallery } from "@mahbub_ali/carousel";

<Gallery
  data={data}
  renderItem={renderSlide}
  height={400}
  showCounter={true}
  autoPlay={true}
/>;
```

### 21. Tinder

Tinder-style swipeable carousel - swipe to navigate.

```javascript
import { Tinder } from "@mahbub_ali/carousel";

<Tinder
  data={data}
  renderItem={renderSlide}
  width={360}
  height={400}
  loop={false}
/>;
```

### 22. Swipeable

Enhanced swipeable carousel - smooth swipe gestures.

```javascript
import { Swipeable } from "@mahbub_ali/carousel";

<Swipeable
  data={data}
  renderItem={renderSlide}
  width={360}
  height={400}
  loop={false}
/>;
```

### 23. Wheel

Wheel rotation carousel - rotates like a wheel.

```javascript
import { Wheel } from "@mahbub_ali/carousel";

<Wheel
  data={data}
  renderItem={renderSlide}
  width={360}
  height={300}
  autoPlay={false}
/>;
```

### 24. Animated

Custom animated carousel - advanced animations.

```javascript
import { Animated } from "@mahbub_ali/carousel";

<Animated
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  scrollAnimationDuration={1000}
/>;
```

---

## With Indicators

### 25. PaginationDots

Carousel with pagination dots - shows dots at bottom, click to navigate.

```javascript
import { PaginationDots } from "@mahbub_ali/carousel";

<PaginationDots
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  dotColor="#007AFF"
  inactiveDotColor="#C7C7CC"
  dotSize={8}
/>;
```

### 26. ProgressBar

Carousel with progress bar - shows progress bar at top.

```javascript
import { ProgressBar } from "@mahbub_ali/carousel";

<ProgressBar
  data={data}
  renderItem={renderSlide}
  autoPlay={true}
  progressColor="#007AFF"
  progressHeight={4}
/>;
```

## Props

### Common Props (All Carousels)

| Prop             | Type     | Default     | Description                  |
| ---------------- | -------- | ----------- | ---------------------------- |
| data             | Array    | []          | Array of data items          |
| renderItem       | Function | required    | Function to render each item |
| width            | Number   | screenWidth | Carousel width               |
| height           | Number   | 300         | Carousel height              |
| loop             | Boolean  | true        | Enable infinite loop         |
| autoPlay         | Boolean  | false       | Enable auto-play             |
| autoPlayInterval | Number   | 2000        | Auto-play interval in ms     |
| onSnapToItem     | Function | -           | Callback when item changes   |
| style            | Object   | -           | Container style              |

### Parallax Specific Props

| Prop                    | Type   | Default | Description           |
| ----------------------- | ------ | ------- | --------------------- |
| parallaxScrollingScale  | Number | 0.9     | Parallax scale factor |
| parallaxScrollingOffset | Number | 50      | Parallax offset       |

### Parallax Specific Props

| Prop                    | Type   | Default | Description           |
| ----------------------- | ------ | ------- | --------------------- |
| parallaxScrollingScale  | Number | 0.9     | Parallax scale factor |
| parallaxScrollingOffset | Number | 50      | Parallax offset       |

### Thumbnail Specific Props

| Prop                 | Type     | Default | Description                  |
| -------------------- | -------- | ------- | ---------------------------- |
| renderThumbnail      | Function | -       | Function to render thumbnail |
| thumbnailSize        | Number   | 60      | Thumbnail size               |
| thumbnailSpacing     | Number   | 10      | Spacing between thumbnails   |
| activeThumbnailStyle | Object   | -       | Style for active thumbnail   |

### PaginationDots Specific Props

| Prop             | Type   | Default   | Description        |
| ---------------- | ------ | --------- | ------------------ |
| dotColor         | String | "#007AFF" | Active dot color   |
| inactiveDotColor | String | "#C7C7CC" | Inactive dot color |
| dotSize          | Number | 8         | Dot size           |

### ProgressBar Specific Props

| Prop           | Type   | Default   | Description         |
| -------------- | ------ | --------- | ------------------- |
| progressColor  | String | "#007AFF" | Progress bar color  |
| progressHeight | Number | 4         | Progress bar height |

### Gallery Specific Props

| Prop        | Type    | Default | Description                  |
| ----------- | ------- | ------- | ---------------------------- |
| showCounter | Boolean | true    | Show counter in bottom-right |

### Animated Specific Props

| Prop                    | Type   | Default  | Description              |
| ----------------------- | ------ | -------- | ------------------------ |
| scrollAnimationDuration | Number | 1000     | Animation duration in ms |
| animationType           | String | 'spring' | Animation type           |

## Quick Start Example

```javascript
import React from "react";
import { View, Text, StyleSheet } from "react-native";
import { BasicHorizontal } from "@mahbub_ali/carousel";

const App = () => {
  const data = [
    { id: 1, title: "Slide 1", color: "#FF6B6B" },
    { id: 2, title: "Slide 2", color: "#4ECDC4" },
    { id: 3, title: "Slide 3", color: "#45B7D1" },
  ];

  return (
    <View style={styles.container}>
      <BasicHorizontal
        data={data}
        renderItem={({ item }) => (
          <View style={[styles.slide, { backgroundColor: item.color }]}>
            <Text style={styles.text}>{item.title}</Text>
          </View>
        )}
        autoPlay={true}
        loop={true}
        height={300}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingTop: 50,
  },
  slide: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    borderRadius: 20,
    marginHorizontal: 10,
  },
  text: {
    fontSize: 32,
    fontWeight: "bold",
    color: "#fff",
  },
});

export default App;
```

## Complete Examples

Check the `example/` directory for a complete demo app with all 26 carousel types.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Tips & Best Practices

### 1. Performance Optimization

- Use `useMemo` for `renderItem` function if it's complex
- Avoid heavy computations in `renderItem`
- Use `onSnapToItem` callback for lazy loading

### 2. Auto-play Settings

- Set appropriate `autoPlayInterval` (2000-3000ms recommended)
- Disable auto-play for user-interactive carousels (Tinder, Swipeable)
- Use `loop={false}` for carousels with limited items

### 3. Customization

- All carousels accept `style` prop for container styling
- Use `width` and `height` props to control carousel dimensions
- Customize colors for indicators (dots, progress bar)

### 4. When to Use Which Carousel

| Use Case            | Recommended Carousel              |
| ------------------- | --------------------------------- |
| Simple image slider | `BasicHorizontal` or `Banner`     |
| Product showcase    | `Parallax` or `Coverflow`         |
| Image gallery       | `Gallery` or `Thumbnail`          |
| Card-based UI       | `Stack` or `CardDeck`             |
| Smooth transitions  | `Fade` or `Scale`                 |
| 3D effects          | `Cube` or `Flip`                  |
| User interaction    | `Tinder` or `Swipeable`           |
| Progress indication | `PaginationDots` or `ProgressBar` |

## Common Issues & Solutions

### Issue: Carousel not animating smoothly

**Solution**: Make sure `react-native-reanimated` is properly installed and configured.

### Issue: Auto-play not working

**Solution**: Check if `autoPlay` prop is set to `true` and `autoPlayInterval` is set correctly.

### Issue: Loop not working

**Solution**: Ensure you have at least 2 items in your data array for loop to work properly.

### Issue: Gestures not responding

**Solution**: Wrap your app with `GestureHandlerRootView` from `react-native-gesture-handler`.

## Support

If you encounter any issues or have questions, please open an issue on GitHub.