ScrollBox

Version 2.0 - Modern vanilla JavaScript scrolling plugin 🎉

📦 Note: This package is available on npm as @wmh/scrollbox. It's a modern, dependency-free vanilla JavaScript library with optional jQuery support for backward compatibility.

ScrollBox is a lightweight, zero-dependency plugin that enables you to scroll a list of HTML elements (text, images, etc.) like a carousel slider or traditional marquee. Built with modern ES6+ JavaScript with optional jQuery support for backward compatibility.

Features

• ✨ Zero dependencies - Pure vanilla JavaScript
• 🚀 Modern ES6+ with backward compatibility
• 📦 Simple and lightweight (~5KB minified)
• ↕️ Vertical and horizontal scroll
• ▶️ Auto play with customizable timing
• 🔄 Multiple instances on one page
• ⏸️ Pause on hover
• 🎛️ Extensive configuration options
• ⬅️➡️ Prev / Next navigation buttons
• 🎯 Queue container for advanced usages
• 🔌 Optional jQuery plugin wrapper for legacy support
• 🐛 Bug fixes for Chrome scroll jumping (Issue #38)
• 📱 Better handling of browser zoom/resize (Issue #37)

Installation

NPM

npm install @wmh/scrollbox

Note: This is a modern vanilla JavaScript library with zero dependencies! Optional jQuery wrapper included for backward compatibility.

CDN

<script src="https://cdn.jsdelivr.net/npm/@wmh/scrollbox@2/dist/scrollbox.min.js"></script>

Direct Download

Download scrollbox.js or jquery.scrollbox.js from this repository.

GitHub

git clone https://github.com/wmh/scrollbox.git

Basic Usage

Modern Vanilla JavaScript (Recommended)

1. Include ScrollBox

<script src="scrollbox.js"></script>

2. Create HTML structure

<div id="demo" class="scroll-text">
  <ul>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
  </ul>
</div>

3. Style your elements

.scroll-text {
  width: 300px;
  height: 100px;
  overflow: hidden;
}

4. Initialize

const element = document.getElementById('demo');
const scrollbox = new ScrollBox(element, {
  direction: 'vertical',
  autoPlay: true
});

jQuery (Legacy Support)

1. Include jQuery and ScrollBox

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="jquery.scrollbox.js"></script>

2. Initialize with jQuery

$('#demo').scrollbox({
  direction: 'vertical',
  autoPlay: true
});

API Methods

Vanilla JavaScript

const scrollbox = new ScrollBox(element, options);

// Trigger events
element.dispatchEvent(new Event('forward'));
element.dispatchEvent(new Event('backward'));
element.dispatchEvent(new CustomEvent('resetClock', { detail: { delay: 5 } }));
element.dispatchEvent(new CustomEvent('speedUp', { detail: { speed: 16 } }));
element.dispatchEvent(new CustomEvent('speedDown', { detail: { speed: 64 } }));
element.dispatchEvent(new CustomEvent('updateConfig', { 
  detail: { autoPlay: false, speed: 50 } 
}));

// Destroy instance
scrollbox.destroy();

jQuery API

$('#demo').trigger('forward');
$('#demo').trigger('backward');
$('#demo').trigger('resetClock', [5]);
$('#demo').trigger('speedUp', [16]);
$('#demo').trigger('speedDown', [64]);
$('#demo').trigger('updateConfig', [{ autoPlay: false }]);

Migration Guide (v1 to v2)

If you're using jQuery (minimal changes needed)

Your existing code should work with minimal changes. Just update to the latest version.

Migrating to Vanilla JavaScript (recommended)

// Old jQuery way
$('#demo').scrollbox({ direction: 'vertical' });
$('#demo').trigger('forward');

// New vanilla JS way
const scrollbox = new ScrollBox(document.getElementById('demo'), {
  direction: 'vertical'
});
document.getElementById('demo').dispatchEvent(new Event('forward'));

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)
• IE 11+ (with transpiled ES5 version)

Demos

http://wmh.github.io/scrollbox/

Configuration Options

Option	Type	Default	Description
linear	Boolean	false	Use linear scrolling animation
startDelay	Number	2	Initial delay before scrolling starts (seconds)
delay	Number	3	Delay between scroll events (seconds)
step	Number	5	Distance of each step in pixels (for linear mode)
speed	Number	32	Animation speed in milliseconds
switchItems	Number	1	Number of items to switch per scroll
direction	String	'vertical'	Scroll direction: 'vertical' or 'horizontal'
distance	String/Number	'auto'	Scroll distance or 'auto'
autoPlay	Boolean	true	Enable auto-scrolling
onMouseOverPause	Boolean	true	Pause on mouse hover
infiniteLoop	Boolean	true	Enable infinite looping
switchAmount	Number	0	Total switches before stopping (0 = infinite)
afterForward	Function	null	Callback after forward scroll
afterBackward	Function	null	Callback after backward scroll
triggerStackable	Boolean	false	Allow stacking trigger events

Advanced Examples

Non-infinite Loop (Vanilla JS)

const scrollbox = new ScrollBox(document.getElementById('demo'), {
  infiniteLoop: false,
  switchAmount: 3
});

With Callback Functions (Vanilla JS)

const scrollbox = new ScrollBox(document.getElementById('demo'), {
  afterForward: function(data) {
    console.log('Scrolled forward', data.switchCount);
    if (data.switchCount >= 3) {
      // Trigger backward
      const event = new Event('backward');
      this.dispatchEvent(event);
    }
  },
  afterBackward: function(data) {
    console.log('Scrolled backward', data);
  }
});

Manual Controls (Vanilla JS)

const scrollbox = new ScrollBox(document.getElementById('demo'), {
  autoPlay: false
});

// Control with buttons
document.getElementById('forward-btn').addEventListener('click', () => {
  const event = new Event('forward');
  document.getElementById('demo').dispatchEvent(event);
});

document.getElementById('backward-btn').addEventListener('click', () => {
  const event = new Event('backward');
  document.getElementById('demo').dispatchEvent(event);
});

jQuery Examples (Legacy)

// Non-infinite loop
$('#demo').scrollbox({
  infiniteLoop: false,
  switchAmount: 3
});

// With callbacks
$('#demo').scrollbox({
  afterForward: function (data) {
    console.log(data.currentFirstChild);
    if (data.switchCount >= 3) {
      $(this).trigger('backward');
    }
  },
  afterBackward: function (data) {
    console.log(data);
  }
});

// Manual controls
$('#forward-btn').click(function() {
  $('#demo').trigger('forward');
});
$('#backward-btn').click(function() {
  $('#demo').trigger('backward');
});

Support the Project

If you find ScrollBox helpful, consider sponsoring me on GitHub ☕ Your support helps maintain and improve this project!

License

jQuery Scrollbox is open-sourced software licensed under the MIT license