@fyndx/react-native-swipe-carousel

A performant swipe carousel component for React Native built with react-native-reanimated and react-native-gesture-handler. Features smooth animations, gesture-based navigation, and customizable styling.

Features

• 🎯 Smooth Animations - Powered by react-native-reanimated for 60fps animations
• 👆 Gesture Support - Swipe gestures with velocity-based snapping
• 🎨 Customizable - Custom item rendering, sizes, spacing, and gradient borders
• 📱 TypeScript - Full TypeScript support with generics
• ⚡ Performant - Optimized with worklets and shared values

Installation

npm install @fyndx/react-native-swipe-carousel

Demo

Peer Dependencies

This library requires the following peer dependencies:

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

Make sure to follow the setup instructions for:

• react-native-gesture-handler
• react-native-reanimated

Usage

Basic Example

import { Carousel } from '@fyndx/react-native-swipe-carousel';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { useState } from 'react';
import { Image, View, Text } from 'react-native';

type Item = {
  id: string;
  image: string;
  title: string;
};

const items: Item[] = [
  { id: '1', image: 'https://example.com/image1.jpg', title: 'Item 1' },
  { id: '2', image: 'https://example.com/image2.jpg', title: 'Item 2' },
  { id: '3', image: 'https://example.com/image3.jpg', title: 'Item 3' },
];

export default function App() {
  const [selectedItem, setSelectedItem] = useState<Item>(items[0]);

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Carousel
        items={items}
        selectedItem={selectedItem}
        onItemChange={setSelectedItem}
        getItemId={(item) => item.id}
        renderItem={(item) => (
          <Image
            source={{ uri: item.image }}
            style={{ width: 200, height: 200, borderRadius: 100 }}
          />
        )}
        renderDetail={(item) => (
          <View>
            <Text>{item.title}</Text>
          </View>
        )}
      />
    </GestureHandlerRootView>
  );
}

Advanced Example

<Carousel
  items={items}
  selectedItem={selectedItem}
  onItemChange={setSelectedItem}
  getItemId={(item) => item.id}
  renderItem={(item, index, translateX) => (
    <YourCustomItemComponent item={item} />
  )}
  renderDetail={(item) => <YourDetailView item={item} />}
  itemSize={250}
  itemSpacing={220}
  minScale={0.7}
  maxScale={1.0}
  showGradientBorder={true}
  gradientColors={['#FF6B6B', '#4ECDC4', '#45B7D1']}
  gradientId="my-carousel-gradient"
/>

API Reference

Carousel<T extends CarouselItemBase>

The main carousel component.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | items | T[] | Yes | - | Array of items to display in the carousel | | selectedItem | T | Yes | - | Currently selected item | | onItemChange | (item: T) => void | Yes | - | Callback fired when the selected item changes | | getItemId | (item: T) => string | Yes | - | Function to extract a unique ID from an item | | renderItem | (item: T, index: number, translateX: SharedValue<number>) => React.ReactNode | Yes | - | Function to render each carousel item | | renderDetail | (item: T) => React.ReactNode | No | - | Optional function to render detail view below carousel | | itemSize | number | No | 192 | Size (width/height) of each carousel item | | itemSpacing | number | No | 200 | Horizontal spacing between items | | minScale | number | No | 0.7 | Minimum scale for items away from center | | maxScale | number | No | 1.0 | Maximum scale for the centered item | | showGradientBorder | boolean | No | true | Whether to show gradient border around centered item | | gradientColors | string[] | No | ['orange', 'blue', 'violet'] | Colors for the gradient border | | gradientId | string | No | 'carousel-gradient' | Unique ID for the SVG gradient (required if multiple carousels) |

Types

// Base type that items must extend
type CarouselItemBase = {
  image: ImageSource; // string | ImageSourcePropType
};

// Image source type
type ImageSource = string | ImageSourcePropType;

Features Explained

Gesture Handling

The carousel responds to pan gestures:

• Swipe left/right to navigate between items
• Velocity-based snapping - fast swipes skip to adjacent items
• Smooth spring animations when snapping to items

Animations

• Scale animation: Items scale from minScale to maxScale based on distance from center
• Opacity animation: Items fade from MIN_OPACITY (0.6) to MAX_OPACITY (1.0) based on position
• Spring physics: Uses configurable damping and stiffness for natural motion

Gradient Border

The optional gradient border highlights the centered item with a customizable gradient stroke. You can:

• Toggle visibility with showGradientBorder
• Customize colors with gradientColors array
• Use unique gradientId when multiple carousels are present

Notes

• Wrap your app (or carousel container) with GestureHandlerRootView from react-native-gesture-handler
• The renderItem function receives a translateX SharedValue that you can use for advanced animations
• Items must have an image property (can be a string URL or ImageSourcePropType)

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library