A lightweight, dependency-free infinite scrolling carousel component with grab-and-drag interaction, momentum scrolling, and seamless looping
npm install grab-n-drag-infinite-carouselbash
npm install grab-n-drag-infinite-carousel
`
Then import using one of the following:
Use the root entry (package default) for development/unminified; use dist/ paths for production/minified.
`javascript
// ES Modules (development - unminified)
import InfiniteScrollCarousel from 'grab-n-drag-infinite-carousel';
import 'grab-n-drag-infinite-carousel/grab-n-drag-infinite-carousel.css';
// ES Modules (production - minified)
import InfiniteScrollCarousel from 'grab-n-drag-infinite-carousel/dist/grab-n-drag-infinite-carousel.min.js';
import 'grab-n-drag-infinite-carousel/dist/grab-n-drag-infinite-carousel.min.css';
// CommonJS (development - unminified)
const InfiniteScrollCarousel = require('grab-n-drag-infinite-carousel');
require('grab-n-drag-infinite-carousel/grab-n-drag-infinite-carousel.css');
// CommonJS (production - minified)
const InfiniteScrollCarousel = require('grab-n-drag-infinite-carousel/dist/grab-n-drag-infinite-carousel.min.js');
require('grab-n-drag-infinite-carousel/dist/grab-n-drag-infinite-carousel.min.css');
`
$3
`html
`
$3
Download the files directly from npm or this repository:
Development (unminified):
- grab-n-drag-infinite-carousel.js
- grab-n-drag-infinite-carousel.css
Production (minified):
- dist/grab-n-drag-infinite-carousel.min.js
- dist/grab-n-drag-infinite-carousel.min.css
$3
TypeScript definitions are included! If you're using TypeScript, you'll get full type checking and IntelliSense support:
`typescript
import InfiniteScrollCarousel, { InfiniteScrollCarouselOptions } from 'grab-n-drag-infinite-carousel';
const options: InfiniteScrollCarouselOptions = {
speed: 50,
pauseOnHover: true
};
const carousel = new InfiniteScrollCarousel('#myCarousel', options);
`
Quickstart
$3
`html
Item 1
Item 2
Item 3
`
That's it! The carousel will automatically start scrolling. For production, use the dist/ paths or the CDN minified links from the Installation section above.
API Reference
$3
`javascript
new InfiniteScrollCarousel(container, options)
`
Parameters:
- container (HTMLElement or string) - The container element or CSS selector
- options (Object, optional) - Configuration object
$3
| Option | Type | Default | Description |
|------|------|---------|-------------|
| speed | number | 50 | Auto-scroll speed in pixels per second. Use 0 to turn off auto-scroll. |
| reverseDirection | boolean | false | If false, content scrolls right to left; if true, scrolls left to right. |
| fadeColor | string | #ffffff | Color of the left/right edge fade (hex, rgb, or rgba). Use 'transparent' to hide. |
| fadeWidth | number | 50 | Width of the edge fade in pixels. |
| momentumDecay | number | 0.05 | How quickly drag momentum fades after release (0.01ā0.5). Higher = stops sooner. |
| maxMomentumSpeed | number | 2.0 | Maximum momentum speed after release, in px/ms (0.5ā25). |
| disableMomentum | boolean | false | If true, no momentum after release; position snaps and auto-scroll resumes. |
| pauseOnHover | boolean | true | If true, auto-scroll pauses while the pointer is over the carousel. |
| interactable | boolean | true | If true, users can drag; if false, drag is disabled. |
| copies | number | 3 | Number of full item sets cloned for the infinite loop (3ā100). |
$3
| Method | Description |
|--------|-------------|
| pause() | Pause automatic scrolling. |
| resume() | Resume paused scrolling. |
| setSpeed(value) | Set scroll speed in pixels per second. |
| setReverseDirection(value) | Set scroll direction. |
| setFadeColor(color) | Set edge fade color and re-apply to wrapper. |
| setFadeWidth(value) | Set fade width in pixels and re-apply to wrapper. |
| destroy() | Clean up event listeners and reset the carousel. Call when removing the carousel from the page. |
$3
| Callback | Type | Description |
|----------|------|-------------|
| onReady | () => void | Fires when carousel initialization completes |
| onDragStart | () => void | Fires when user starts dragging |
| onDrag | (position: number, deltaX: number) => void | Fires during drag movement (throttled) |
| onDragEnd | () => void | Fires when user ends dragging |
| onMomentumStart | (velocity: number) => void | Fires when momentum scrolling begins |
| onMomentumEnd | () => void | Fires when momentum scrolling ends |
| onPositionReset | () => void | Fires when position resets during seamless loop |
| onPause | () => void | Fires when carousel is paused |
| onResume | () => void | Fires when carousel is resumed |
> š For detailed API documentation, examples, and advanced usage, see DOCS.md
Examples
$3
`html
Item 1
Item 2
Item 3
Item 4
Item 5
`
$3
`html
Item 1
Item 2
Item 3
`
View interactive examples with code ā
> š For more examples including React/Vue integration, advanced use cases, and styling guides, see DOCS.md
Browser Compatibility
ā
Chrome 64+, Firefox 69+, Safari 13.1+, Edge 79+
ā
Mobile support (iOS Safari 13.1+, Android Chrome 64+)
Requires: requestAnimationFrame, CSS transform, addEventListener (ResizeObserver has fallback support)
Troubleshooting
Items not scrolling? Ensure CSS is loaded and container has direct children.
Drag not working? Check that interactable: true and no CSS is blocking pointer events.
Items too close? Add margin: .infinite-scroll-item { margin-right: 30px; }
Speed issues? Adjust the speed option (set to 0` to disable auto-scroll).