QuickSlide

A modular, plugin-based slider engine for React. Built with performance, accessibility, and extreme extensibility in mind.

Features

• 🧩 Plugin-based Architecture: Only include the features you need.
• 🔄 Infinite Loop: Seamless infinite scrolling with clone-based correction.
• 🖱️ Touch & Drag Support: Smooth hardware-accelerated transitions.
• ⌨️ Keyboard & Wheel Navigation: Full control via arrows, home/end, and scroll.
• 🚀 Performance Optimized: Uses CSS translate3d for GPU-accelerated movement.
• 🎨 Headless Design: Total control over your slide markup and styling.
• 📦 Zero Logic Dependencies: Core engine is independent of styling frameworks.

Installation

pnpm add quick-slide
# or
npm install quick-slide

Documentation

For more detailed information, please refer to the following guides:

• Plugin System & Built-in Plugins - Learn how to use and create plugins.
• Contributing Guide - Development setup and contribution rules.

Basic Usage

import { QuickSlide } from "quick-slide"
import {
    navigationPlugin,
    dragPlugin,
    autoplayPlugin,
} from "quick-slide/plugins"
import "quick-slide/styles.css"

const images = [
    { src: "1.jpg", title: "Slide 1" },
    { src: "2.jpg", title: "Slide 2" },
]

export default function Gallery() {
    return (
        <div className="h-96 w-full">
            <QuickSlide
                items={images}
                infinite={true}
                transitionDuration={600}
                renderSlide={(item) => (
                    <img
                        src={item.src}
                        alt={item.title}
                        className="h-full w-full object-cover"
                    />
                )}
                plugins={[
                    dragPlugin(),
                    autoplayPlugin({ interval: 5000 }),
                    navigationPlugin(),
                ]}
            />
        </div>
    )
}

Plugins

QuickSlide is powered by a powerful plugin system. Available built-in plugins:

| Plugin | Description | | :------------------------- | :-------------------------------------------------------- | | autoplayPlugin | Automatically advances slides at set intervals. | | dragPlugin | Enables mouse and touch drag navigation. | | navigationPlugin | Adds previous and next navigation buttons. | | indicatorsPlugin | Adds pagination dots/indicators. | | keyboardNavigationPlugin | Enables arrow key, Home, and End navigation. | | wheelNavigationPlugin | Enables mouse wheel and trackpad navigation. | | imagePreloaderPlugin | Smart preloading for images to ensure smooth transitions. |

Example: Using Wheel Navigation

import { wheelNavigationPlugin } from "quick-slide/plugins"

// ... inside plugins array
wheelNavigationPlugin({
    threshold: 30,
    cooldown: 400,
    preventDefault: true,
})

Custom Components

You can build your own components using the Backdrop effect (as seen in our example gallery) to create immersive experiences.

import { Backdrop } from "./components/backdrop";

// Use it alongside QuickSlide to create crossfading backgrounds
<div className="relative overflow-hidden">
  <Backdrop src={images[currentIndex].src} />
  <QuickSlide ... />
</div>

API Reference

QuickSlide Props

| Prop | Type | Default | Description | | :--------------------- | :------------------------------------------------ | :---------- | :------------------------------------- | | items | T[] | Required | Array of data items to render. | | renderSlide | (item: T, state: SlideRenderState) => ReactNode | Required | Render function for individual slides. | | infinite | boolean | true | Enable infinite looping. | | transitionDuration | number | 500 | Transition speed in ms. | | plugins | SliderPlugin[] | [] | List of plugins to activate. | | currentIndex | number | undefined | Controlled index. | | onCurrentIndexChange | (index: number) => void | undefined | Callback when index changes. |

Imperative API

Access the slider controls via ref:

const ref = useRef<QuickSlideRef>(null)

ref.current?.next()
ref.current?.previous()
ref.current?.goTo(2)

License

MIT