npm package: @nokrei/react-smooth-carousel
Description: A smooth, infinite carousel with drag support for React
Author: Nokrei
Latest version: 0.1.0

# React Smooth Carousel

A smooth, infinite carousel component with drag support for React. Built using the Web Animations API for 60fps performance.

## Features

- **Smooth infinite scrolling** - Seamless looping with Web Animations API
- **Mouse and touch drag** - Full support for mouse and touch interactions
- **Bidirectional** - Scroll forward or reverse
- **Responsive** - Automatically adapts to container size changes
- **60fps** - Hardware-accelerated animations
- **Fully customizable** - Render any content with complete styling control
- **Zero dependencies** - Only requires React as peer dependency
- **TypeScript** - Full type safety with TypeScript support
- **Accessible** - Built with ARIA labels for screen readers

## Installation

```bash
npm install @nokrei/react-smooth-carousel
```

```bash
yarn add @nokrei/react-smooth-carousel
```

```bash
pnpm add @nokrei/react-smooth-carousel
```

## Quick Start

```tsx
import { Carousel } from '@nokrei/react-smooth-carousel';

type Product = {
  _key: string;
  name: string;
  image: string;
};

function ProductCarousel() {
  const products: Product[] = [
    { _key: '1', name: 'Product 1', image: '/product1.jpg' },
    { _key: '2', name: 'Product 2', image: '/product2.jpg' },
    { _key: '3', name: 'Product 3', image: '/product3.jpg' },
  ];

  return (
    <Carousel
      items={products}
      renderItem={(product) => (
        <div style={{ width: '300px', padding: '20px' }}>
          <img src={product.image} alt={product.name} />
          <h3>{product.name}</h3>
        </div>
      )}
    />
  );
}
```

## Usage Examples

### Basic Carousel

```tsx
import { Carousel } from '@nokrei/react-smooth-carousel';

function App() {
  const items = [
    { _key: '1', content: 'Slide 1' },
    { _key: '2', content: 'Slide 2' },
    { _key: '3', content: 'Slide 3' },
  ];

  return (
    <Carousel
      items={items}
      renderItem={(item) => <div>{item.content}</div>}
    />
  );
}
```

### Reverse Direction

```tsx
<Carousel
  items={items}
  renderItem={(item) => <Card {...item} />}
  direction="reverse"
/>
```

### Custom Animation Speed

```tsx
<Carousel
  items={items}
  renderItem={(item) => <Card {...item} />}
  animationDuration={30000} // 30 seconds per loop
/>
```

### Disable Pause on Hover

```tsx
<Carousel
  items={items}
  renderItem={(item) => <Card {...item} />}
  pauseOnHover={false}
/>
```

### Dual Carousel (Split Layout)

Create a dual carousel effect by using two carousel instances:

```tsx
function DualCarousel() {
  const items = [...]; // Your items
  const midpoint = Math.ceil(items.length / 2);
  const topItems = items.slice(0, midpoint);
  const bottomItems = items.slice(midpoint);

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <Carousel
        items={topItems}
        renderItem={(item) => <Card {...item} />}
        direction="forward"
      />
      <Carousel
        items={bottomItems}
        renderItem={(item) => <Card {...item} />}
        direction="reverse"
      />
    </div>
  );
}
```

### Disable Drag Interactions

```tsx
<Carousel
  items={items}
  renderItem={(item) => <Card {...item} />}
  enableMouseDrag={false}
  enableTouchDrag={false}
/>
```

## API Reference

### Carousel Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `T[]` | **required** | Array of items to display. Each item must have a `_key` property |
| `renderItem` | `(item: T) => ReactNode` | **required** | Function to render each carousel item |
| `direction` | `"forward" \| "reverse"` | `"forward"` | Direction of carousel scrolling |
| `animationDuration` | `number` | `25000` | Duration of one complete loop in milliseconds |
| `duplicateCount` | `number` | `6` | Number of times to duplicate the item set (affects smoothness) |
| `transitionDuration` | `number` | `100` | Duration of transition when resuming after drag (ms) |
| `resumeDelay` | `number` | `500` | Delay before resuming animation after mouse leave (ms) |
| `pauseOnHover` | `boolean` | `true` | Whether to pause animation on hover |
| `enableMouseDrag` | `boolean` | `true` | Enable mouse drag interaction |
| `enableTouchDrag` | `boolean` | `true` | Enable touch drag interaction |
| `gap` | `string` | `"1rem"` | CSS gap value between items |
| `className` | `string` | `""` | Additional CSS class for wrapper div |
| `style` | `CSSProperties` | `undefined` | Additional inline styles for wrapper div |
| `containerClassName` | `string` | `""` | Additional CSS class for container div |
| `ariaLabel` | `string` | `"Carousel"` | ARIA label for accessibility |

### Types

```tsx
import type {
  CarouselItem,
  CarouselProps,
  CarouselDirection,
  RenderItem,
} from '@nokrei/react-smooth-carousel';

// Base type for carousel items
type CarouselItem = {
  _key: string;
  [key: string]: unknown;
};

// Render function type
type RenderItem<T extends CarouselItem> = (item: T) => ReactNode;

// Direction type
type CarouselDirection = "forward" | "reverse";
```

## Advanced Usage

### Using Hooks Directly

The carousel exposes low-level hooks for advanced use cases:

```tsx
import { useCarouselDrag, useCarouselTouchDrag } from '@nokrei/react-smooth-carousel';

// Use in your custom carousel implementation
```

### Custom Styling

The carousel provides minimal layout styles. You have full control over item appearance:

```tsx
<Carousel
  items={products}
  renderItem={(product) => (
    <div className="custom-card">
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
    </div>
  )}
  gap="2rem"
  className="my-carousel-wrapper"
  containerClassName="my-carousel-container"
/>
```

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari 14+
- iOS Safari 14+
- Android Chrome (latest)

Requires browsers with Web Animations API support.

## Performance

The carousel uses the Web Animations API with hardware-accelerated CSS transforms for optimal performance. It automatically handles:

- ResizeObserver for responsive updates
- Debounced animation recreation on resize
- Efficient infinite scrolling without DOM manipulation

## Contributing

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

## License

MIT © Nokrei