Carousel & Marquee Like Scrolling List Plguin - Scrollbox.js

Scrollbox is a lightweight yet customizable JavaScript scrolling plugin that enables you to create smooth vertical or horizontal content carousels with jQuery or Vanilla JavaScript.

This plugin is the successor to the popular jquery-scrollbox.It works with pure ES6+ JavaScript while maintaining optional jQuery support for legacy projects.

See Also:

• 10 Best Marquee-like Content Scrolling Plugins In JavaScript
• 10 Best News Ticker Plugins In jQuery And Pure JavaScript/CSS

Features:

• Simple and lightweight.
• Supports both vertical and horizontal scrolling.
• Auto play and pause on hover.
• Multiple instances on one page.
• Linear step-based scrolling or smooth easing animations. 
• Feeds new content dynamically from a separate container during scroll cycles.
• Prev / Next navigation buttons.
• Configurable timing, speed, distance, and loop behavior.
• Includes an optional wrapper for jQuery projects.

Use Cases:

• News Tickers and Live Updates: Display breaking news, stock prices, or real-time notifications in a continuously scrolling banner across your site header or sidebar.
• Product Showcases: Create product carousels on e-commerce sites where items scroll automatically but users can pause and interact when interested.
• Social Media Feeds: Showcase Twitter feeds, Instagram posts, or testimonials in a vertical scrolling container that keeps fresh content visible without user interaction.
• Event Announcements: Display upcoming events, webinar schedules, or promotional messages in waiting rooms, dashboards, or informational displays where constant content rotation is needed.

How To Use It:

1. Download the Scrollbox plugin directly or install it via NPM.

# NPM
$ npm install jquery-scrollbox

2. Include the main script on your webpage.

<!-- Vanilla JavaScript -->
<script src="/path/to/scrollbox.js"></script>

<!-- jQuery -->
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/jquery.scrollbox.js"></script>

3. Create a container div with an unordered list ul inside. The library targets the list items li for scrolling.

<div id="news-ticker" class="scroll-container">
  <ul>
    <li>Breaking News: ScrollBox v2.0 Released</li>
    <li>Update: Zero dependencies included</li>
    <li>Feature: Vertical and Horizontal support</li>
    <li>Guide: Check the API documentation below</li>
  </ul>
</div>

4. Style the container to control the visible area and hide overflow.

.scroll-container {
  width: 100%;
  height: 40px; /* Defines the visible height of the ticker */
  overflow: hidden; /* Hides the scrolling items */
  border: 1px solid #ddd;
}

.scroll-container ul {
  margin: 0;
  padding: 0;
  list-style: none;
}

.scroll-container li {
  height: 40px; /* Should match container height for single-line tickers */
  line-height: 40px;
  padding-left: 10px;
}

5. Select the DOM element and instantiate the ScrollBox plugin.

// Vanilla JavaScript
const container = document.getElementById('news-ticker');
const myScrollBox = new ScrollBox(container, {
  // options here
});

// jQuery
$('#news-ticker').scrollbox({
  // options here
});

6. All configuration options:

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

{
  linear: false,
  startDelay: 2,
  delay: 3,
  step: 5,
  speed: 32,
  switchItems: 1,
  direction: 'vertical',
  distance: 'auto',
  autoPlay: true,
  onMouseOverPause: true,
  paused: false,
  queue: null,
  listElement: 'ul',
  listItemElement: 'li',
  infiniteLoop: true,
  switchAmount: 0,
  afterForward: null,
  afterBackward: null,
  triggerStackable: false,
}

7. API methods and events. ScrollBox v2+ uses standard DOM events for control. This decouples the logic from specific UI elements. You control the instance by dispatching events to the container element.

Control Events

• forward: Triggers the list to scroll forward one step.
• backward: Triggers the list to scroll backward one step.
• resetClock: Resets the internal timer. Requires detail object with delay.
• speedUp: Increases scrolling speed. Requires detail object with speed.
• speedDown: Decreases scrolling speed. Requires detail object with speed.
• updateConfig: Updates configuration dynamically. Requires detail object with new options.
• pauseHover: Manually pauses the auto-play functionality.
• forwardHover: Resumes auto-play.

Instance Methods

• destroy(): Stops the scroller and removes event listeners.

8. Here's an advanced demo showing how to create a fully controlled scroller with start, stop, and direction buttons.

<div class="scroller-wrapper">
  <div id="controlled-scroll" class="scroll-container">
    <ul>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
      <li>Item 4</li>
      <li>Item 5</li>
    </ul>
  </div>
  <div class="controls">
    <button id="btn-backward">Previous</button>
    <button id="btn-forward">Next</button>
    <button id="btn-faster">Speed Up</button>
    <button id="btn-slower">Slow Down</button>
  </div>
</div>

/ Initialize without auto-scrolling
const scrollbox = new ScrollBox(document.getElementById('controlled-scroll'), {
  autoPlay: false,          // Disable automatic scrolling
  direction: 'horizontal',  // Set horizontal scroll mode
  speed: 50                 // Slower initial speed for better control
});

// Get control buttons
const element = document.getElementById('controlled-scroll');
const btnForward = document.getElementById('btn-forward');
const btnBackward = document.getElementById('btn-backward');
const btnFaster = document.getElementById('btn-faster');
const btnSlower = document.getElementById('btn-slower');

// Trigger forward scroll on button click
btnForward.addEventListener('click', () => {
  element.dispatchEvent(new Event('forward'));
});

// Trigger backward scroll on button click
btnBackward.addEventListener('click', () => {
  element.dispatchEvent(new Event('backward'));
});

// Increase scroll speed dynamically
btnFaster.addEventListener('click', () => {
  // Pass new speed value in milliseconds (lower = faster)
  element.dispatchEvent(new CustomEvent('speedUp', { 
    detail: { speed: 25 } 
  }));
});

// Decrease scroll speed dynamically
btnSlower.addEventListener('click', () => {
  // Pass new speed value in milliseconds (higher = slower)
  element.dispatchEvent(new CustomEvent('speedDown', { 
    detail: { speed: 100 } 
  }));
});

FAQs:

Q: Can I dynamically add new items to the scrolling list while it's running?
A: Yes. Use the queue configuration option to specify a separate container element that holds new content. ScrollBox automatically pulls items from this queue container during scroll cycles.

Q: Why does my horizontal scroll not work correctly when browser zoom is changed?
A: ScrollBox 2 improved handling of browser zoom and resize events. The library recalculates distances based on computed styles rather than cached dimensions.

Q: Can I use different HTML tags instead of <ul> and <li>?
A: Yes. Use the listElement and listItemElement configuration options. For example, listElement: 'div', listItemElement: 'p' will make ScrollBox look for a div containing p tags.

Changelog:

v2.0.0 (2025-12-04)

• Complete rewrite in ES6+ class syntax

v1.4.2 (2015-11-21)

• Fix event binding arguments

v1.4.1 (2015-04-09)

• Update.

v1.2.0 (2015-01-17)

• Update.

v1.2.0 (2014-07-24)

• Update.

v1.0.5 (2014-03-19)

• Add an example for forwardHover. 

v1.0.5 (2013-12-01)

• Fix choppy scrolling. 

v1.0.4 (2013-11-17)

• Selector fix

---

This awesome jQuery plugin is developed by wmh. For more Advanced Usages, please check the demo page or visit the official website.