Spark Slider

Lightweight and fast React carousel slider powered by Framer Motion animations

Try the live demo: spark-slider.vercel.app

Project repo: github.com/AshBuk/framer-motion-spark-slider

Lightweight React carousel built with Framer Motion. Framework-agnostic by default (renders with <img>), with an escape hatch to inject next/image. Designed as a modern and highly optimized solution for large image datasets, it works seamlessly across laptops, tablets, and phones.

Features

• Smooth drag-to-swipe with momentum-free, precise control
• Click on center card to select (single tap on touch)
• Auto-play with pause on interaction and hidden tab detection
• Responsive layout using viewport units (svh/svmin)
• Keyboard navigation (arrow keys)
• Accessibility features with ARIA support
• Performance: renders only visible cards, lazy loading for non-center images
• Framework-agnostic: works with Next.js, Vite, Create React App, Remix, Gatsby, and any React framework

✦ Installation

npm install @ashbuk/spark-slider
# or
yarn add @ashbuk/spark-slider
# or
pnpm add @ashbuk/spark-slider

Peer dependencies (install separately if not already in your project):

npm install framer-motion react react-dom

Requirements: React 18+, Framer Motion 12+

✦ Usage

import { SparkSlider, SLIDER_CONFIG } from '@ashbuk/spark-slider';
import '@ashbuk/spark-slider/dist/spark-slider.css';

export default function Example() {
  const images = [
    'https://picsum.photos/id/1015/1600/1200',
    'https://picsum.photos/id/1016/1600/1200',
    'https://picsum.photos/id/1018/1600/1200',
  ];
  return (
    <SparkSlider
      images={images}
      alt='Image'
      autoPlayInterval={SLIDER_CONFIG.DEFAULT_AUTOPLAY_INTERVAL_MS}
      className='[--spark-slider-h:60svh]'
    />
  );
}

API Reference

Note: Public API is annotated with TSDoc. Most editors will show inline documentation on hover.

SparkSlider Props

| Prop | Type | Description | | -------------------- | ----------------------------------- | ---------------------------------- | | images | string[] | Array of image URLs or paths | | alt? | string | Alt text for images | | autoPlayInterval? | number | Auto-play interval in milliseconds | | className? | string | CSS classes for container | | cardClassName? | string | CSS classes for each card wrapper | | renderImage? | (src, alt, isCenter) => ReactNode | Custom image renderer | | onSlideSelect? | (index: number) => void | Called when slide is selected | | onSelectionChange? | (index: number) => void | Called when selection changes |

Package Breakdown

Component:

• SparkSlider – Main slider component
• SLIDER_CONFIG – Configuration constants and defaults
• useSparkSlider – Core slider state management hook
• useSparkKeyboard – Keyboard navigation hook
• useSparkTransforms – Card positioning and transforms hook
• useSparkFullscreen – Fullscreen overlay management hook
• computeSwipeTarget – Swipe gesture calculation utility
• CardPosition – TypeScript type for card positions

Styling

• Ships with a prebuilt stylesheet: @ashbuk/spark-slider/dist/spark-slider.css (import required)
• Height can be set via CSS var --spark-slider-h using svh units
• Custom styling via className and cardClassName props

Development (monorepo)

• This package is developed inside a Next.js demo app. In dev, the package sources under packages/spark-slider/src/spark are a symbolic link to the app sources src/components/SparkSlider/* to avoid duplication.
• The app imports by package name and Next is configured with transpilePackages: ['@ashbuk/spark-slider'] for hot reload.
• Build locally:

npm -w packages/spark-slider run build

Support

• GitHub Issues: Report bugs or request features
• Contributions welcome! See CONTRIBUTING.md

License

MIT — see LICENSE