Snap-carousel.js NPM

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

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.