Vertex Scroller

A high-performance, infinite vertical image scroller with variable speed control and seamless looping. Smooth, responsive, and infinitely fluid.

Author: Abhilash Sahoo · License: MIT

Install

npm install vertex-scroller

Or use from a CDN (no build step) — see Usage with CDN below.

Usage

With npm (bundler / ESM)

import VertexScroller from 'vertex-scroller';
import 'vertex-scroller/index.css';

const scroller = new VertexScroller(document.querySelector('#my-scroller'), {
  speed: 1.5,
  showSpeedControl: true,
  enableModal: true,
  data: [/* optional array of { title, desc, baseHeight, urlThumbBase, urlLargeBase } */]
});

With script tag (browser, from node_modules)

<div id="my-scroller"><!-- cards or leave empty for data-driven --></div>

<link rel="stylesheet" href="node_modules/vertex-scroller/index.css">
<script type="module">
  import VertexScroller from './node_modules/vertex-scroller/index.js';
  document.addEventListener('DOMContentLoaded', () => {
    new VertexScroller(document.querySelector('#my-scroller'), {
      speed: 1.5,
      showNavigationButtons: true,
      showSpeedControl: true,
      enableModal: true
    });
  });
</script>

With CDN (unpkg)

<link rel="stylesheet" href="https://unpkg.com/vertex-scroller@1/index.css">
<script type="module">
  import VertexScroller from 'https://unpkg.com/vertex-scroller@1';
  document.addEventListener('DOMContentLoaded', () => {
    new VertexScroller(document.querySelector('#my-scroller'), { speed: 1.5 });
  });
</script>

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | speed | number | 1.5 | Scroll speed (pixels per frame). | | gap | number | 32 | Gap between cards (px). | | showNavigationButtons | boolean | true | Show prev/next list buttons. | | showSpeedControl | boolean | true | Show speed slider. | | showPlayPauseButton | boolean | true | Show play/pause button. | | showPauseOnHover | boolean | true | Show pause-on-hover toggle. | | enableModal | boolean | true | Enable full-screen modal on card click. | | enableModalAutoplay | boolean | true | Enable modal slideshow. | | showModalSpeedControl | boolean | true | Show slideshow speed in modal. | | enableMouseWheel | boolean | true | Allow mouse wheel to scroll. | | enableCaptions | boolean | true | Show title/desc on cards and in modal. | | loadThreshold | number | 800 | Distance (px) from viewport edge to add items. | | removeThreshold | number | 1000 | Distance (px) from viewport edge to remove items. | | modalAutoplayInterval | number | 3000 | Modal slideshow interval (ms). | | data | array | [] | Optional items: { title, desc, baseHeight, urlThumbBase?, urlLargeBase?, urlBase? }. |

Cleanup

scroller.destroy(); // Stops animation, removes listeners, clears DOM

Demo: vertex-scroller.vercel.app · Download: Use the “Download demo (ZIP)” button on the demo page.

Features

Scrolling & motion

• Infinite vertical scrolling — Seamless looping with no end; content is generated and removed dynamically.
• Variable scroll speed — Adjustable via slider (0.5×–8×) for list and optional separate speed control in the modal.
• Smooth scroll — Animated scroll when using prev/next buttons (eased, ~500ms).
• RequestAnimationFrame loop — Smooth, efficient animation with no layout thrashing.

Input & interaction

• Mouse wheel — Scroll up/down with the wheel or trackpad (optional, can be disabled).
• Touch & drag — Swipe vertically on the track to scroll; drag vs click is distinguished so taps still open the modal.
• Hover to pause — Optional pause-on-hover so the list stops when the pointer is over the scroller.
• Play / Pause — Optional button to start or stop auto-scroll.
• Pause-on-hover toggle — Optional control to enable/disable “pause when hovering” without leaving the page.
• Prev / Next buttons — Optional list navigation that smooth-scrolls by one step (e.g. ~300px).
• Click to open modal — Click a card to open a full-screen modal (when modal is enabled).

Full-screen modal

• Full-screen image viewer — Click a card to view the image large with optional title and description.
• Separate thumb & large URLs — List uses thumbnails (data-thumb / urlThumbBase); modal uses high-res (data-large / urlLargeBase).
• Modal navigation — Prev/Next buttons and keyboard (← / →) to move between images.
• Swipe in modal — Touch swipe left/right to go to previous/next image (configurable threshold).
• Keyboard — Escape to close; ← / → for prev/next image.
• Modal autoplay — Optional slideshow with configurable interval (e.g. 1–5 seconds).
• Modal speed control — Optional slider in the modal to change slideshow interval.
• Click backdrop — Click outside the image to close the modal.

Content & data

• Static HTML cards — Use your own markup with data-thumb, data-large, data-jx-title, data-jx-desc, and optional placeholder divs.
• Programmatic data — Pass a data array with title, desc, baseHeight, and urlThumbBase / urlLargeBase (or urlBase) to generate cards.
• Captions — Optional title and description on cards and in the modal (enableCaptions).
• Configurable gap — Space between cards (e.g. 32px) is configurable.

Performance & behavior

• Virtual list — Items are added when near the viewport (loadThreshold) and removed when far (removeThreshold) to keep the DOM small.
• Lazy loading — Images load via Intersection Observer; configurable root margin and max concurrent loads.
• Load priority — Images are loaded in order of distance from the viewport center.
• Resize handling — ResizeObserver keeps the list filled when the container size changes (e.g. window resize).
• Cleanup — destroy() cancels animation frame, intervals, observers, and event listeners for safe teardown.

UI customization (all optional)

• Control panel — Show/hide the bottom pill: play/pause, speed slider, pause-on-hover toggle.
• Navigation buttons — Show/hide prev/next list buttons.
• Modal — Enable/disable the full-screen viewer.
• Modal autoplay & speed — Show/hide autoplay button and speed slider in the modal.
• Captions — Show/hide titles and descriptions on cards and in the modal.
• Visual polish — Top and bottom fade edges on the scroll area.

API & usage

• Class-based API — Single constructor: new VertexScroller(rootElement, config); supports multiple instances.
• Keyboard (list) — When the scroller has focus: ↑ / ↓ for prev/next, Space for play/pause (if play/pause is enabled).
• Global export — VertexScroller is attached to window when using the script in a classic <script> setup.

Run Locally

Prerequisites: Node.js

1. Clone the repo:

   git clone https://github.com/abhilashsahoo/vertex-scroller.git
   cd vertex-scroller

2. Install dependencies:

   npm install

3. Run the app:

   npm run dev

Scripts

| Command | Description | | ------------ | -------------------- | | npm run dev | Start development server | | npm run build | Build for production | | npm run preview| Preview production build |

Publishing to npm

If you are the maintainer and want to publish updates:

1. Log in: npm login
2. Bump version (e.g. npm version patch) or set in package.json
3. Publish: npm publish

Only index.js and index.css are included in the package (see "files" in package.json).

License

MIT © Abhilash Sahoo