Spin Slider

A modern, accessible carousel/slider component for React with TypeScript support.

Features

• 🎯 TypeScript Support - Full TypeScript support with generic types
• ♿ Accessible - ARIA attributes and keyboard navigation
• 📱 Touch & Mouse Support - Swipe gestures and mouse drag
• 🎨 Customizable - Extensive styling and behavior options
• 🔄 Auto Play - Optional auto-play with configurable intervals
• ♾️ Infinite Loop - Optional infinite scrolling
• 📊 Pagination - Built-in pagination with smart page display
• 🎛️ Navigation - Optional navigation buttons
• 📐 Responsive - Responsive design with viewport-based sizing

Installation

npm install spin-slider

Quick Start

import { SpinSlider } from 'spin-slider';

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

function App() {
  return (
    <SpinSlider
      items={items}
      renderItem={item => (
        <div>
          <img src={item.image} alt={item.title} />
          <h3>{item.title}</h3>
        </div>
      )}
      visibleCount={3}
      autoPlay
      infinite
    />
  );
}

Props

SpinSliderProps

| Prop | Type | Default | Description | | -------------------- | --------------------------------------- | ------- | ---------------------------------- | | items | T[] | - | Array of items to display | | renderItem | (item: T, index: number) => ReactNode | - | Function to render each item | | visibleCount | number | 1 | Number of items visible at once | | sidePeek | number | 32 | Side peek amount in pixels | | autoPlay | boolean | false | Enable auto-play | | autoPlayInterval | number | 3000 | Auto-play interval in milliseconds | | infinite | boolean | false | Enable infinite loop | | showPagination | boolean | true | Show pagination dots | | showNavigation | boolean | true | Show navigation buttons | | minSwipeDistance | number | 50 | Minimum swipe distance | | transitionDuration | number | - | Custom transition duration | | initialIndex | number | 0 | Initial slide index | | styles | SpinSliderStyles | - | Custom styles | | callbacks | SpinSliderCallbacks | - | Event callbacks | | accessibility | SpinSliderAccessibility | - | Accessibility options | | className | string | - | CSS class name |

SpinSliderStyles

| Prop | Type | Default | Description | | ------------------------- | -------- | ------------------------------ | ------------------------- | | trackTransition | string | 'transform 0.3s ease-in-out' | Track transition CSS | | buttonSize | number | 40 | Navigation button size | | paginationDotSize | number | 32 | Pagination dot size | | buttonBackground | string | 'rgba(255, 255, 255, 0.9)' | Button background color | | buttonColor | string | '#333' | Button text color | | activePaginationColor | string | '#007bff' | Active pagination color | | inactivePaginationColor | string | '#ddd' | Inactive pagination color |

SpinSliderCallbacks

| Prop | Type | Description | | ----------------- | ---------------------------------- | ---------------------------- | | onSlideChange | (currentIndex: number) => void | Called when slide changes | | onItemClick | (item: T, index: number) => void | Called when item is clicked | | onSwipeStart | () => void | Called when swipe starts | | onSwipeEnd | () => void | Called when swipe ends | | onAutoPlayStart | () => void | Called when auto-play starts | | onAutoPlayStop | () => void | Called when auto-play stops |

Examples

Basic Usage

<SpinSlider items={items} renderItem={item => <div>{item.title}</div>} />

Multiple Items Visible

<SpinSlider items={items} renderItem={item => <div>{item.title}</div>} visibleCount={3} sidePeek={16} />

Auto-play with Infinite Loop

<SpinSlider items={items} renderItem={item => <div>{item.title}</div>} autoPlay autoPlayInterval={2000} infinite />

Custom Styling

<SpinSlider
  items={items}
  renderItem={item => <div>{item.title}</div>}
  styles={{
    buttonSize: 50,
    buttonBackground: '#ff6b6b',
    buttonColor: '#fff',
    activePaginationColor: '#ff6b6b',
  }}
/>

Event Handling

<SpinSlider
  items={items}
  renderItem={item => <div>{item.title}</div>}
  callbacks={{
    onSlideChange: index => console.log('Slide changed to:', index),
    onItemClick: (item, index) => console.log('Clicked item:', item, 'at index:', index),
  }}
/>

Accessibility

<SpinSlider
  items={items}
  renderItem={item => <div>{item.title}</div>}
  accessibility={{
    label: 'Product carousel',
    previousButtonLabel: 'Previous product',
    nextButtonLabel: 'Next product',
    paginationLabel: 'Product navigation',
  }}
/>

Hooks

useSwipe

Custom hook for handling swipe gestures:

import { useSwipe } from 'spin-slider';

const { handleTouchStart, handleTouchEnd, handleMouseDown, handleMouseUp } = useSwipe({
  onSwipeLeft: () => console.log('Swiped left'),
  onSwipeRight: () => console.log('Swiped right'),
  minSwipeDistance: 50,
});

Utilities

The library also exports utility functions:

import {
  getVisiblePages,
  getRenderRange,
  getNextIndex,
  getPreviousIndex,
  isValidIndex,
  getCurrentPage,
  getTotalPages,
} from 'spin-slider';

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT