@mahbub_ali/carousel

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

Installation

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

Peer Dependencies

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

For Expo projects:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

15. HorizontalStack

Stacked cards in horizontal direction.

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

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

16. VerticalStack

Stacked cards in vertical direction.

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

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

17. CardDeck

Card deck style - stacked like playing cards.

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

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

18. Accordion

Accordion style - expand/collapse effect.

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.

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.

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.

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.

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.

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

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

24. Animated

Custom animated carousel - advanced animations.

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.

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.

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

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.