ScrollBox

Features

Installation

NPM

npm install @wmh/scrollbox

CDN

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

Direct Download

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)

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

Demos

Configuration Options

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

License