SenangWebs Roll (SWR)

A lightweight, responsive roll library for creating mobile-like media rolls similar to Instagram Reels or YouTube Shorts.

Features

Multiple Media Types: Support for images, videos, and custom HTML content
Two Initialization Methods: HTML data attributes or JavaScript API
Touch & Keyboard Navigation: Swipe gestures and arrow key support
Seamless Infinite Scrolling: Natural wrap-around animation when looping (like Instagram Reels)
Smart Autoplay: Automatically enables looping for continuous playback
Mouse Drag & Wheel Support: Full desktop navigation with mouse drag and wheel scrolling
Customizable: Flexible configuration for aspect ratios, autoplay, looping, and more
Lightweight & Responsive: Optimized for both mobile and desktop devices
No Dependencies: Pure vanilla JavaScript, no external libraries required
Event System: Custom events for complete control over roll behavior
Accessible: Keyboard navigation and accessibility-friendly markup

Quick Start

Installation

Include the compiled CSS and JS files in your HTML:

<link rel="stylesheet" href="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.css">
<script src="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.js"></script>

Method 1: JavaScript API (Recommended)

<link rel="stylesheet" href="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.css">

<div id="myRoll"></div>

<script src="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.js"></script>
<script>
const roll = new SWR('#myRoll', {
    aspectRatio: '9:16',
    loop: true,
    autoplay: true,
    autoplayInterval: 5000,
    items: [
        {
            type: 'video',
            src: 'video.mp4',
            muted: true,
            playsinline: true
        },
        {
            type: 'image',
            src: 'image.jpg',
            alt: 'Demo Image'
        },
        {
            type: 'html',
            content: '<div style="height: 100%; display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white;"><h1>Custom Slide</h1></div>'
        }
    ]
});
</script>

Method 2: HTML Data Attributes

<link rel="stylesheet" href="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.css">
<!-- Automatically initializes on page load - no JavaScript required! -->
<div data-swr 
     data-swr-aspect-ratio="9:16" 
     data-swr-loop="true"
     data-swr-autoplay="true"
     data-swr-autoplay-interval="5000">
    <div data-swr-item>
        <video autoplay muted playsinline loop>
            <source src="video.mp4" type="video/mp4">
        </video>
    </div>
    <div data-swr-item>
        <img src="image.jpg" alt="Image">
    </div>
    <div data-swr-item>
        <div style="height: 100%; display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white;">
            <h1>Custom Content</h1>
        </div>
    </div>
</div>
<script src="https://unpkg.com/senangwebs-roll@latest/dist/swr.min.js"></script>

Configuration Options

Option	Type	Default	Description
`aspectRatio`	string	`'9:16'`	Aspect ratio of the roll (e.g., '9:16', '16:9', '1:1')
`loop`	boolean	`false`	Enable infinite looping through items (auto-enabled when `autoplay` is true)
`autoplay`	boolean	`false`	Start autoplay automatically on load (automatically enables `loop` if not explicitly set)
`autoplayInterval`	number	`5000`	Time between autoplay slides (milliseconds)
`enableKeyboard`	boolean	`true`	Enable arrow key navigation
`enableTouch`	boolean	`true`	Enable swipe gesture navigation
`enableWheel`	boolean	`true`	Enable mouse wheel navigation
`enableMouseDrag`	boolean	`true`	Enable mouse drag navigation
`enableAutoplayPauseOnInteraction`	boolean	`true`	Pause autoplay on user interaction
`autoplayResumeDelay`	number	`3000`	Delay before resuming autoplay (milliseconds)
`transitionDuration`	number	`350`	Animation duration for slides (milliseconds)
`swipeThreshold`	number	`50`	Minimum swipe distance to trigger navigation (pixels)

Data Attribute Configuration

Use HTML data attributes for configuration:

<div data-swr
  data-swr-aspect-ratio="9:16"
  data-swr-loop="true"
  data-swr-autoplay="true"
  data-swr-autoplay-interval="4000"
  data-swr-keyboard="true"
  data-swr-touch="true"
  data-swr-transition="300"
  data-swr-swipe-threshold="40">

API Reference

Methods

Navigation

next() - Navigate to next item
prev() - Navigate to previous item
goTo(index) - Jump to specific item index

Item Management

addItem(item, index) - Add new item to the roll (optionally at specific index)
removeItem(index) - Remove item at index
getCurrentIndex() - Get current active item index
getTotalItems() - Get total number of items

Playback Control

play() - Start autoplay
pause() - Pause autoplay
isPlaying() - Check if autoplay is active

Event System

on(event, callback) - Subscribe to event
off(event, callback) - Unsubscribe from event
getConfig() - Get current configuration

Lifecycle

destroy() - Destroy instance and clean up resources

Events

initialized - Emitted when roll is initialized
navigationChanged - Emitted when active item changes
slideStarted - Emitted when slide animation starts
slideCompleted - Emitted when slide animation completes
autoplayStart - Emitted when autoplay starts
autoplayPause - Emitted when autoplay pauses
autoplayTick - Emitted on each autoplay interval tick
autoplayPausedTemporarily - Emitted when autoplay pauses temporarily
swipeDetected - Emitted when swipe is detected
tapDetected - Emitted when tap is detected (toggles autoplay)
keyboardEvent - Emitted on keyboard interaction
wheelDetected - Emitted when mouse wheel is used
dragDetected - Emitted when mouse drag is detected
beforeRender - Emitted before item renders
afterRender - Emitted after item renders
itemAdded - Emitted when item is added
itemRemoved - Emitted when item is removed
itemUpdated - Emitted when item is updated
itemsCleared - Emitted when all items are cleared
destroy - Emitted when instance is destroyed

Item Object Structure

Video Item

{
    type: 'video',
    src: 'path/to/video.mp4',
    mimeType: 'video/mp4',
    autoplay: true,
    muted: true,
    playsinline: true,
    loop: false
}

Image Item

{
    type: 'image',
    src: 'path/to/image.jpg',
    alt: 'Image description',
    title: 'Image title'
}

HTML Item

{
    type: 'html',
    content: '<div>HTML content</div>'
}

Seamless Infinite Scrolling

SWR features intelligent wrap-around animation that creates a natural, continuous scrolling experience similar to Instagram Reels:

Natural Direction: When swiping up on the last item, it smoothly continues upward to the first item (not jarring downward jump)
Intuitive Flow: When swiping down on the first item, it smoothly continues downward to the last item
Automatic Loop: When autoplay: true is set, loop is automatically enabled for continuous playback
Seamless Transitions: Uses optimized CSS transforms for smooth, GPU-accelerated animations

How It Works

// Autoplay automatically enables loop for seamless continuous playback
const roll = new SWR('#roll', {
    autoplay: true,  // loop is automatically set to true
    autoplayInterval: 3000
});

// Or manually enable loop for seamless infinite scrolling
const roll2 = new SWR('#roll2', {
    loop: true  // Enables seamless wrap-around navigation
});

Examples

Example 1: Basic Setup with Autoplay

const roll = new SWR('#roll', {
    autoplay: true,  // Loop is auto-enabled
    autoplayInterval: 3000
});

Example 2: Manual Loop Control

// Disable automatic loop enabling (if you want autoplay to stop at the end)
const roll = new SWR('#roll', {
    autoplay: true,
    loop: false,  // Explicitly set to false to override auto-enabling
    autoplayInterval: 3000
});

Example 3: Event Handling

const roll = new SWR('#roll');

// Listen to item changes
roll.on('navigationChanged', (data) => {
    console.log(`Now showing item ${data.newIndex + 1} of ${data.totalItems}`);
});

// Listen to slide completion
roll.on('slideCompleted', (data) => {
    console.log('Slide animation completed');
});

// Control autoplay
roll.on('autoplayStart', () => {
    console.log('Autoplay started');
});

// Listen to user interactions
roll.on('swipeDetected', (data) => {
    console.log('Swipe direction:', data.direction);
});

roll.on('tapDetected', () => {
    console.log('Tap detected - autoplay toggled');
});

Example 4: Dynamic Content Management

const roll = new SWR('#roll');

// Add items dynamically
roll.addItem({
    type: 'image',
    src: 'new-image.jpg',
    alt: 'New Image'
});

// Add at specific position
roll.addItem({
    type: 'video',
    src: 'video.mp4',
    muted: true
}, 1);

// Remove items
roll.removeItem(0);

// Navigate programmatically
roll.next();  // Go to next item
roll.prev();  // Go to previous item
roll.goTo(2); // Jump to specific item

// Check current state
console.log(`Total items: ${roll.getTotalItems()}`);
console.log(`Current index: ${roll.getCurrentIndex()}`);
console.log(`Is playing: ${roll.isPlaying()}`);

Example 5: Full-Featured Setup

const roll = new SWR('#roll', {
    aspectRatio: '9:16',
    autoplay: true,
    autoplayInterval: 4000,
    transitionDuration: 500,
    enableKeyboard: true,
    enableTouch: true,
    enableWheel: true,
    enableMouseDrag: true,
    enableAutoplayPauseOnInteraction: true,
    autoplayResumeDelay: 2000,
    swipeThreshold: 50,
    items: [
        { type: 'video', src: 'video1.mp4', muted: true },
        { type: 'image', src: 'image1.jpg', alt: 'Image' },
        { type: 'html', content: '<div class="custom-slide">Content</div>' }
    ]
});

// Listen to all events
roll.on('initialized', () => console.log('Ready!'));
roll.on('slideCompleted', (data) => console.log('Slide:', data.index));
roll.on('autoplayStart', () => console.log('Playing'));
roll.on('autoplayPause', () => console.log('Paused'));

Example 6: Custom Styling

/* Override default aspect ratio */
.my-roll .swr-viewport {
    aspect-ratio: 16 / 9;
}

/* Customize item styling */
.my-roll [data-swr-item] {
    border-radius: 8px;
}

/* Custom transition */
.my-roll .swr-container {
    transition-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
}

Navigation Controls

Keyboard

Arrow Down / Arrow Right - Next item
Arrow Up / Arrow Left - Previous item
Space - Toggle autoplay

Touch/Mouse

Swipe Up / Drag Up - Next item
Swipe Down / Drag Down - Previous item
Tap/Click - Toggle autoplay
Mouse Wheel Up - Previous item
Mouse Wheel Down - Next item

Responsive Behavior

The roll automatically adapts to different screen sizes:

Mobile (< 768px) - Aspect ratio 9:16, optimized for portrait viewing
Desktop (≥ 768px) - Aspect ratio 16:9, optimized for landscape viewing

Customize aspect ratios via configuration.

Important Behaviors

Autoplay and Loop

When autoplay: true is set, loop is automatically enabled (unless explicitly set to false)
This ensures continuous playback without stopping at the last item
To disable auto-looping, explicitly set loop: false in your configuration

Seamless Wrap Animation

When loop: true, navigating from the last item to the first (or vice versa) uses a seamless animation
The animation direction matches the user's gesture for an intuitive experience
Swipe up on last item → continues upward to first item
Swipe down on first item → continues downward to last item

Interaction Pausing

When enableAutoplayPauseOnInteraction: true, user interactions (swipe, tap, keyboard, wheel, drag) temporarily pause autoplay
Autoplay resumes after autoplayResumeDelay milliseconds
Tap/click on the roll toggles autoplay on/off

Accessibility

Keyboard navigation support (arrow keys)
Semantic HTML markup
Focus management
High contrast support
Reduced motion support (via prefers-reduced-motion)

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
dist		dist
examples		examples
src		src
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
swr_preview.png		swr_preview.png
webpack.config.js		webpack.config.js

Folders and files

Latest commit

History

Repository files navigation

SenangWebs Roll (SWR)

Features

Quick Start

Installation

Method 1: JavaScript API (Recommended)

Method 2: HTML Data Attributes

Configuration Options

Data Attribute Configuration

API Reference

Methods

Navigation

Item Management

Playback Control

Event System

Lifecycle

Events

Item Object Structure

Video Item

Image Item

HTML Item

Seamless Infinite Scrolling

How It Works

Examples

Example 1: Basic Setup with Autoplay

Example 2: Manual Loop Control

Example 3: Event Handling

Example 4: Dynamic Content Management

Example 5: Full-Featured Setup

Example 6: Custom Styling

Navigation Controls

Keyboard

Touch/Mouse

Responsive Behavior

Important Behaviors

Autoplay and Loop

Seamless Wrap Animation

Interaction Pausing

Accessibility

Browser Support

License

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages