Tiny Touch Carousel Web Component for Modern Apps – Pure Swipe Slider

Pure Swipe Slider is a web component library that creates high-performance,  touch-enabled carousels using Web Components API, Pointer Events, and GPU-accelerated transforms.

It ships as a custom element that works across React, Vue, Angular, and vanilla JavaScript projects.

Features:

• Minimal Bundle Size: Ships at 3.5KB gzipped with zero runtime dependencies.
• Unified Input Handling: Processes touch, mouse, wheel, and pen inputs through Pointer Events API.
• GPU Acceleration: Uses translate3d transforms and will-change hints for 60fps animations on mobile devices.
• Custom Events Interface: Dispatches standard CustomEvent objects for state changes and user interactions.
• Flexible Content Support: Supports images, text, dates, complex layouts, and dynamically added slides.
• Two Usage Modes: Available as <swipe-slider> web component or swipe3.js low-level engine.

How To Use It:

1. Install the package through npm and import the registration module to use the default <swipe-slider> tag:

npm install pure-swipe-slider

import 'pure-swipe-slider/register.js';

2. Add the HTML structure:

<swipe-slider draggable mousewheel>
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</swipe-slider>

3. You can also register the web component with a custom tag name:

// Import the class separately for manual registration
import SwipeSlider from 'pure-swipe-slider';
import 'pure-swipe-slider/swipe-slider.css';
// Define your own custom element name
customElements.define('product-carousel', SwipeSlider);

<product-carousel draggable mousewheel>
  <div>Product A</div>
  <div>Product B</div>
  <div>Product C</div>
</product-carousel>

4. Configure behavior through the following HTML attributes.

• start-slide (Number): Sets the initial slide index. Defaults to 0.
• speed (Number): Controls transition duration in milliseconds. Defaults to 400.
• draggable (Boolean): Activates mouse drag functionality. Defaults to false.
• mousewheel (Boolean): Activates scroll wheel navigation. Defaults to true. Use no-mousewheel attribute to disable.
• disable-scroll (Boolean): Prevents vertical page scrolling during horizontal swipes. Defaults to false.
• stop-propagation (Boolean): Stops event bubbling to parent elements. Defaults to false.
• passive-events (Boolean): Uses passive event listeners for better scroll performance. Breaks preventDefault behavior. Defaults to false.
• loop (Boolean): Creates infinite circular scrolling by moving slides dynamically. Defaults to false.
• auto-height (Boolean or Number): Adjusts container height to match current slide. Optional numeric value sets minimum height. Defaults to false.

5. API methods.

const slider = document.querySelector('swipe-slider');
// Navigate to next slide
slider.next();
// Navigate to previous slide
slider.prev();
// Jump to specific slide (zero-indexed)
slider.slide(2);
// Get current position
const currentIndex = slider.getPos();
console.log(`Currently at slide ${currentIndex}`);
// Get total slide count
const total = slider.getNumSlides();
console.log(`Total slides: ${total}`);
// Create new slide element
const newSlide = document.createElement('div');
newSlide.textContent = 'Dynamic Slide';
// Add to end
slider.appendSlide(newSlide);
// Add to beginning
slider.prependSlide(newSlide);
// Reinitialize after major DOM changes
slider.setup();

6. Attach event listeners for slide changes and user interactions:

const slider = document.querySelector('swipe-slider');
// Fires when the active slide changes
slider.addEventListener('swipe:change', (e) => {
  const { index, element, direction } = e.detail;
  console.log(`Now showing slide ${index}`);
  // direction: -1 for previous, 1 for next
  console.log(`User swiped ${direction === 1 ? 'forward' : 'back'}`);
});
// Fires when CSS transition completes
slider.addEventListener('swipe:transition-end', (e) => {
  console.log('Transition finished');
  // Execute post-transition logic here
});
// Fires when user starts dragging
slider.addEventListener('swipe:drag-start', (e) => {
  console.log('User initiated drag');
  // Pause video playback, disable other interactions, etc.
});
// Fires when user releases drag gesture
slider.addEventListener('swipe:drag-end', (e) => {
  // e.detail: { index, element }
  console.log(e.detail);
});
// Fires continuously during movement (high-frequency)
slider.addEventListener('swipe:move', (e) => {
  // Use sparingly - triggers on every pixel of movement
  console.log('Moving');
});

7. For advanced use cases or legacy setups that need direct control, import the core engine:

import Swipe from 'pure-swipe-slider/swipe3.js';
const container = document.getElementById('slider-container');
// Initialize with configuration object
const swipeInstance = Swipe(container, {
  speed: 400,
  startSlide: 0,
  draggable: true,
  mousewheel: true,
  
  // Callback fires on slide change
  callback(index, element, direction) {
    console.log(`Changed to slide ${index}`);
  },
  
  // Fires when transition completes
  transitionEnd(index, element) {
    console.log('Transition done');
  },
  
  // Fires when drag starts
  dragStart(index, element) {
    console.log('Drag started');
  },
  
  // Fires when drag ends
  dragEnd(index, element) {
    console.log('Drag ended');
  }
});
// Call API methods
swipeInstance.next();
swipeInstance.prev();
swipeInstance.slide(2);
// Clean up when done
swipeInstance.kill();

#slider-container {
  position: relative;
  overflow: hidden;
  width: 100%;
}
.slides {
  position: relative;
  white-space: nowrap;
}
.slides > * {
  display: inline-block;
  vertical-align: top;
  white-space: normal;
}

Alternatives

• 10 Best JavaScript & CSS Carousel Libraries (2026 Update)

FAQs:

Q: How do I prevent vertical scrolling while swiping horizontally on mobile?
A: Add the disable-scroll attribute to the component. This calls preventDefault on touch events to stop page scrolling during horizontal swipes. Note that this conflicts with passive-events mode.

Q: Can I use this component with server-side rendering frameworks like Next.js?
A: Yes, but import the component only in client-side code. Wrap the import in a dynamic import or useEffect hook to avoid SSR execution. Custom elements require a browser environment with a DOM.

Q: The slider jumps to the wrong slide after adding new slides dynamically. How do I fix this?
A: Call slider.setup() after modifying the DOM structure. The setup method recalculates slide positions and widths. Appending or prepending single slides works without reinitializing.

Q: How do I implement autoplay functionality?
A: The library does not include autoplay. Create a setInterval that calls slider.next() at your desired interval. Clear the interval on swipe:drag-start and restart it on swipe:drag-end to pause during user interaction.

Q: What’s the difference between the web component and the swipe3.js engine?
A: The web component wraps swipe3.js in a custom element with attribute-based configuration and Custom Events. Use the web component for modern projects. Use swipe3.js directly for legacy setups or when you need callback-based architecture instead of events.