Snap Carousel

A modern, lightweight (5.4kB gzip) JavaScript carousel component that leverages the power of CSS scroll-snap and custom element shadow DOM. Perfect for creating responsive, performant, and customizable image galleries, product carousels, and content sliders.

View Demo | Documentation | Installation | Usage

Table of Contents

• Features
• Installation
• Documentation
  • Basic Usage
  • Configuration Options
  • Examples
• Browser Support
• Contributing
• License

Features

• ✨ Lightweight and performant - only 5.4kB gzipped
• 🎯 Previous/Next navigation buttons
• 📍 Pagination indicators
• 🔢 Pager display (e.g., "1 of 6")
• 🔄 loop (CSS-based, no element cloning)
• ⏯️ Autoplay with hover pause
• 📱 Fully responsive configuration
• 🎨 Customizable through shadow DOM
• 🚀 Zero dependencies

Installation

npm install snap-carousel.js
# or
yarn add snap-carousel.js

Documentation

Basic Usage

<snap-carousel>
  <div slot="scroller">
    <div>Slide 1</div>
    <div>Slide 2</div>
    <div>Slide 3</div>
  </div>
</snap-carousel>

<script>
  import 'snap-carousel.js';
</script>

ES Modules Usage

// Import everything
import { SnapCarousel } from 'snap-carousel.js';

// Register the web component
customElements.define('snap-carousel', SnapCarousel);

// Or import specific features
import { BaseCarousel, createCarousel } from 'snap-carousel.js/base-carousel';
import { NavFeature } from 'snap-carousel.js/features/nav';
import { PagerFeature } from 'snap-carousel.js/features/pager';

// Create custom carousel with only navigation and pager
const CustomCarousel = createCarousel(NavFeature, PagerFeature);
customElements.define('custom-carousel', CustomCarousel);

Configuration Options

Option	Type	Default	Description
displayed	number	1	Number of items visible in the viewport at once
perPage	number	1	Number of items to scroll per navigation action
gap	string/number	0	Space between carousel items (CSS units, e.g., "1rem", "16px")
padding	string/number	0	Padding around the carousel viewport (CSS units)
controls	boolean	false	Show previous/next navigation buttons
nav	boolean	false	Show navigation dots for direct slide access
pager	boolean	false	Show current/total slides counter
loop	boolean	false	Enable infinite looping of carousel items
autoplay	number	0	Autoplay interval in milliseconds (0 to disable)
usePause	boolean	true	Pause autoplay on hover
behavior	string	"smooth"	Scroll behavior ("smooth" or "auto")
stop	boolean	false	Force stopping at each step (scroll-snap-stop: always)
vertical	boolean	false	Enable vertical scrolling mode
responsive	array	[]	Breakpoint-specific settings
sync	string	null	Selector for other carousels to sync with

Example responsive configuration:

<snap-carousel
  displayed="1"
  responsive='[{
    "breakpoint": 768,
    "settings": {
      "displayed": 2,
      "perPage": 2
    }
  }, {
    "breakpoint": 1024,
    "settings": {
      "displayed": 3,
      "perPage": 3
    }
  }]'>
  <div slot="scroller">
    <!-- carousel items -->
  </div>
</snap-carousel>

See the Demo page for more examples and configuration options.

Examples

<!-- Basic carousel with navigation -->
<snap-carousel controls nav>
  <div slot="scroller">
    <img src="slide1.jpg" alt="Slide 1">
    <img src="slide2.jpg" alt="Slide 2">
    <img src="slide3.jpg" alt="Slide 3">
  </div>
</snap-carousel>

<!-- Autoplay carousel with pagination -->
<snap-carousel autoplay="5000" nav pager>
  <div slot="scroller">
    <div>Content 1</div>
    <div>Content 2</div>
    <div>Content 3</div>
  </div>
</snap-carousel>

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requires browsers with support for:

• Custom Elements v1
• Shadow DOM v1
• CSS Scroll Snap

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.