🎠 React Native Carousel Image Slider

A modern, customizable, and high-performance carousel slider component for React Native applications. Perfect for showcasing images, banners, or any content that needs a smooth sliding experience.

✨ Features

• 🎯 Fully customizable
• 📱 iOS and Android support
• 🎨 Customizable dots and styling
• 🔄 Auto-play functionality
• ♾️ Infinite loop support
• 🖼️ Custom image component support
• ⚡️ High performance
• 📦 Zero dependencies
• 🔍 TypeScript support

📋 Requirements

• React Native >= 0.72.0
• React >= 18.0.0

🚀 Installation

# Using npm
npm install react-native-carousel-image-slider

# Using yarn
yarn add react-native-carousel-image-slider

🎮 Basic Usage

Function Component Example

import React, { useState } from "react";
import { View } from "react-native";
import { CarouselSlider } from "react-native-carousel-image-slider";

export default function App() {
  const [images, setImages] = useState([]);

  return (
    <View style={{ width: "100%", flex: 1, padding: 24 }}>
      <CarouselSlider images={images} />
    </View>
  );
}

Class Component Example

import React from "react";
import { View } from "react-native";
import { CarouselSlider } from "react-native-carousel-image-slider";

export class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      images: [],
    };
  }

  render() {
    return (
      <View style={{ width: "100%", flex: 1, padding: 24 }}>
        <CarouselSlider images={this.state.images} />
      </View>
    );
  }
}

🎨 Advanced Usage

Using Local Images

import React from "react";
import { View } from "react-native";
import { CarouselSlider } from "react-native-carousel-image-slider";

export default function App() {
  const images = [
    require('./assets/image1.jpg'),
    require('./assets/image2.jpg'),
    require('./assets/image3.jpg'),
  ];

  return (
    <View style={{ width: "100%", flex: 1, padding: 24 }}>
      <CarouselSlider images={images} />
    </View>
  );
}

Using Custom Image Component

import React from "react";
import { View, Image, Text } from "react-native";
import { CarouselSlider } from "react-native-carousel-image-slider";

export default function App() {
  const images = [
    { uri: 'https://example.com/image1.jpg', title: 'Image 1' },
    { uri: 'https://example.com/image2.jpg', title: 'Image 2' },
  ];

  const CustomImage = (item, index) => (
    <View>
      <Image source={{ uri: item.uri }} style={{ width: 300, height: 200 }} />
      <Text>{item.title}</Text>
    </View>
  );

  return (
    <View style={{ width: "100%", flex: 1, padding: 24 }}>
      <CarouselSlider 
        images={images}
        customImageComponent={CustomImage}
        autoPlay={true}
        autoPlayInterval={2000}
      />
    </View>
  );
}

📚 Props

Prop	Type	Default	Description
images	Array	required	Array of image sources (URL strings or require() objects)
renderDots	boolean	true	Whether to show pagination dots
onImagePress	function	undefined	Callback when an image is pressed
activeDotColor	string	'red'	Color of the active dot
inactiveDotColor	string	'gray'	Color of inactive dots
dotStyle	ViewStyle	undefined	Custom style for dots
dotSize	number	8	Size of the dots
dotSpacing	number	4	Spacing between dots
resizeMethod	'auto' | 'resize' | 'scale'	'auto'	Image resize method
resizeMode	ImageResizeMode	'cover'	Image resize mode
imageStyle	ImageStyle	undefined	Custom style for images
disabledOnPress	boolean	false	Disable image press
buttonActiveOpacity	number	1	Opacity when pressing images
autoPlay	boolean	false	Enable auto-play
autoPlayInterval	number	3000	Interval between auto-play slides (ms)
loop	boolean	true	Enable infinite loop
customImageComponent	function	undefined	Custom component to render images
containerStyle	ViewStyle	undefined	Custom style for the container
imageContainerStyle	ViewStyle	undefined	Custom style for the image container
dotsContainerStyle	ViewStyle	undefined	Custom style for the dots container
showNavigationButtons	boolean	false	Show navigation buttons
navigationButtonColor	string	'#fff'	Color of navigation buttons
navigationButtonSize	number	30	Size of navigation buttons
swipeEnabled	boolean	true	Enable swipe gestures
bounceEnabled	boolean	true	Enable bounce effect
scrollEnabled	boolean	true	Enable scroll
overlayStyle	ViewStyle	undefined	Custom style for image overlay
captionStyle	ViewStyle	undefined	Custom style for image caption container
captionTextStyle	TextStyle	undefined	Custom style for caption text
loadingIndicator	ReactNode	undefined	Custom loading indicator component
errorComponent	ReactNode	undefined	Custom error component
onSlideChange	function	undefined	Callback when slide changes
onScroll	function	undefined	Callback during scroll
onScrollBegin	function	undefined	Callback when scroll begins
onScrollEnd	function	undefined	Callback when scroll ends
initialIndex	number	0	Initial slide index
windowSize	number	3	Number of slides to keep in memory
maxToRenderPerBatch	number	3	Maximum number of slides to render per batch
updateCellsBatchingPeriod	number	50	Period for updating cells
accessibilityLabel	string	undefined	Accessibility label
accessibilityHint	string	undefined	Accessibility hint
accessibilityRole	string	'image'	Accessibility role
aspectRatio	number	undefined	Image aspect ratio
height	number	undefined	Custom height for images
width	number	undefined	Custom width for images
longPressEnabled	boolean	false	Enable long press gesture
onLongPress	function	undefined	Callback for long press gesture

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

• Gustavo Castilho - GitHub

⭐️ Show your support

Give a ⭐️ if this project helped you!