@atom_design/carousel

A highly customizable React Native carousel component with auto-play, dots navigation, progress bar, loop support, and full accessibility features. Part of the Atom Design System.

Features

• 🎠 Smooth Scrolling - Native FlatList-based horizontal scrolling
• 🔄 Auto-play - Configurable automatic slide transitions
• 🔁 Loop Mode - Infinite scrolling support
• 📍 Dot Navigation - Customizable pagination dots
• 📊 Progress Bar - Visual progress indicator
• 🎨 Fully Customizable - Style every aspect of the carousel
• ♿ Accessible - Full screen reader support
• 📱 Responsive - Adapts to screen dimensions
• 🖼️ Custom Rendering - Use renderItem for complete control
• 💪 TypeScript Support - Full type definitions included

📦 Installation

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

Peer Dependencies

npm install react react-native prop-types

🚀 Basic Usage

import React from 'react';
import { View } from 'react-native';
import Carousel from '@atom_design/carousel';

const App = () => {
  const slides = [
    { id: 1, background: 'https://picsum.photos/800/400?random=1', content: 'Summer Sale' },
    { id: 2, background: 'https://picsum.photos/800/400?random=2', content: 'New Arrivals' },
    { id: 3, background: 'https://picsum.photos/800/400?random=3', content: 'Best Sellers' },
  ];

  return (
    <View style={{ flex: 1 }}>
      <Carousel
        slides={slides}
        autoPlay
        showDots
        height={200}
      />
    </View>
  );
};

export default App;

🧩 Props

Core Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | slides | SlideItem[] | Required | Array of slide objects to display | | renderSlide | (slide, index, isActive) => ReactNode | undefined | Custom render function for slides | | autoPlay | boolean | true | Enable auto-play functionality | | autoPlayInterval | number | 3000 | Interval between transitions (ms) | | loop | boolean | true | Enable infinite loop scrolling | | showDots | boolean | true | Show navigation dots | | showProgressBar | boolean | true | Show progress bar | | aspectRatio | number | 2.37 | Aspect ratio (width/height) for slides | | height | number | auto | Custom height (overrides aspectRatio) |

Callback Props

| Prop | Type | Description | |------|------|-------------| | onSlideChange | (index) => void | Called when active slide changes | | onSlidePress | (slide, index) => void | Called when a slide is pressed |

Style Props

| Prop | Type | Description | |------|------|-------------| | containerStyle | ViewStyle | Style for the carousel container | | slideStyle | ViewStyle | Style for each slide wrapper | | imageResizeMode | string | Image resize mode: 'cover', 'contain', 'stretch', 'center' |

Dot Customization Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | dotsContainerStyle | ViewStyle | undefined | Style for the dots container | | dotStyle | ViewStyle | undefined | Style for individual dot | | activeDotStyle | ViewStyle | undefined | Style for the active dot | | inactiveColor | string | '#ccc' | Color of inactive dots | | activeColor | string | '#d9232d' | Color of active dot | | dotSize | number | 9 | Size of the dots |

Progress Bar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | progressBarStyle | ViewStyle | undefined | Style for progress bar | | progressBarBackgroundColor | string | '#f0f0f0' | Progress bar background | | progressBarColor | string | '#d9232d' | Progress bar fill color |

Accessibility Props

| Prop | Type | Description | |------|------|-------------| | testID | string | Test ID for testing frameworks |

📁 SlideItem Type

interface SlideItem {
  id?: string | number;
  background: string;           // Image URL or color (hex/rgb)
  content?: string;             // Text overlay
  textStyle?: object;           // Custom text style
  overlayStyle?: object;        // Custom overlay style
  accessibilityLabel?: string;  // Accessibility label
}

✨ Advanced Examples

With Custom Render Slide

<Carousel
  slides={products}
  renderSlide={(slide, index, isActive) => (
    <View style={styles.slide}>
      <Image source={{ uri: slide.background }} style={styles.image} />
      <View style={styles.overlay}>
        <Text style={styles.title}>{slide.content}</Text>
        <Text style={styles.price}>${slide.price}</Text>
        <TouchableOpacity style={styles.button}>
          <Text>Shop Now</Text>
        </TouchableOpacity>
      </View>
    </View>
  )}
  height={300}
  showDots
/>

With Progress Bar

<Carousel
  slides={banners}
  autoPlay
  autoPlayInterval={5000}
  showProgressBar
  showDots={false}
  progressBarColor="#4CAF50"
/>

Custom Styled Dots

<Carousel
  slides={items}
  showDots
  dotSize={10}
  inactiveColor="#cccccc"
  activeColor="#ff6b6b"
  activeDotStyle={{
    width: 24,
    borderRadius: 5,
  }}
  dotsContainerStyle={{
    bottom: 20,
  }}
/>

🧪 Full Test Screen Example

import React from 'react';
import {
  View,
  Text,
  StyleSheet,
  ScrollView,
  SafeAreaView,
  Dimensions,
} from 'react-native';
import Carousel from '@atom_design/carousel';

const { width: SCREEN_WIDTH } = Dimensions.get('window');

// Image slides - uses image URLs
const imageSlides = [
  { id: 1, background: 'https://picsum.photos/800/400?random=1', content: 'Summer Collection' },
  { id: 2, background: 'https://picsum.photos/800/400?random=2', content: 'New Arrivals' },
  { id: 3, background: 'https://picsum.photos/800/400?random=3', content: 'Flash Sale' },
];

// Color slides - uses hex colors
const colorSlides = [
  { id: 1, background: '#d9232d', content: 'Welcome to Moglix' },
  { id: 2, background: '#2196F3', content: 'Best Deals' },
  { id: 3, background: '#4CAF50', content: 'Shop Now' },
];

// Compact slides
const compactSlides = [
  { id: 1, background: 'https://picsum.photos/800/300?random=4' },
  { id: 2, background: 'https://picsum.photos/800/300?random=5' },
  { id: 3, background: 'https://picsum.photos/800/300?random=6' },
];

const CarouselTestScreen = () => {
  return (
    <SafeAreaView style={styles.container}>
      <ScrollView>
        {/* Header */}
        <Text style={styles.header}>Carousel Test</Text>

        {/* Image Carousel */}
        <View style={styles.section}>
          <Text style={styles.sectionTitle}>Image Carousel</Text>
          <Carousel
            slides={imageSlides}
            autoPlay
            autoPlayInterval={3000}
            showDots
            showProgressBar
            height={200}
            onSlideChange={(index) => console.log('Slide:', index)}
          />
        </View>

        {/* Color Carousel */}
        <View style={styles.section}>
          <Text style={styles.sectionTitle}>Color Carousel</Text>
          <Carousel
            slides={colorSlides}
            autoPlay
            autoPlayInterval={2500}
            showDots
            showProgressBar
            height={180}
            activeColor="#fff"
            inactiveColor="rgba(255,255,255,0.5)"
            progressBarColor="#fff"
          />
        </View>

        {/* Compact Carousel */}
        <View style={styles.section}>
          <Text style={styles.sectionTitle}>Compact Carousel</Text>
          <Carousel
            slides={compactSlides}
            height={120}
            showDots
            dotSize={6}
          />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
  header: {
    fontSize: 24,
    fontWeight: 'bold',
    textAlign: 'center',
    marginVertical: 20,
  },
  section: {
    marginBottom: 24,
    paddingHorizontal: 16,
  },
  sectionTitle: {
    fontSize: 16,
    fontWeight: '600',
    marginBottom: 10,
  },
});

export default CarouselTestScreen;

♿ Accessibility

The Carousel component is fully accessible:

• Screen Reader Support: Announces slide changes and positions
• Accessibility Labels: Describes carousel content
• Accessibility Hints: Provides navigation instructions

<Carousel
  data={banners}
  accessibilityLabel="Product showcase carousel"
  accessibilityHint="Swipe left or right to view more products"
/>

📝 TypeScript

Full TypeScript support included:

import Carousel from '@atom_design/carousel';

interface SlideItem {
  id: number;
  background: string;
  content?: string;
}

const slides: SlideItem[] = [
  { id: 1, background: 'https://example.com/img.jpg', content: 'Banner 1' },
  { id: 2, background: '#d9232d', content: 'Color Slide' },
];

const MyCarousel: React.FC = () => (
  <Carousel
    slides={slides}
    autoPlay
    showDots
    onSlideChange={(index: number) => {
      console.log('Current slide:', index);
    }}
  />
);

👤 Author

Atom Design Team

📄 License

MIT © Atom Design