rt-slider

rt-slider is a lightweight JavaScript utility that creates touch-friendly sliders with smooth inertia scrolling and physics with:

• Automatic dependency loading (loads Lenis automatically)
• Zero-config defaults (works out of the box with basic selectors)
• Attribute-driven configuration
• Support for multiple instances
• A clean global API under window.rtSlider
• Defensive fallbacks to native scrolling on mobile
• Built-in slide state tracking, scroll progress tracking, DOM attributes, and custom events for advanced UI sync

Primary dependency (GitHub): https://github.com/darkroomengineering/lenis

Table of Contents

• 1. Installation
  • 1.1 CDN (jsDelivr)
  • 1.2 npm
• 2. Quick Start
• 3. Activation Rules
• 4. Configuration (HTML Attributes)
• 5. Multiple Instances
• 6. Global API
• 7. Console Logging
• 8. Troubleshooting
• 9. License

1. Installation

1.1 CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-slider@latest/dist/index.min.js"></script>

1.2 npm

npm install @rethink-js/rt-slider

Then bundle or load dist/index.min.js as appropriate for your build setup.

2. Quick Start

Add the script to your page. To create a slider, add the data-rt-slider attribute to a container and specify the child selectors.

rt-slider will:

• Auto-initialize on DOM ready
• Load Lenis dynamically for desktop inertia
• Apply native touch scrolling styles for mobile
• Compute active slide state and overall scroll progress automatically
• Expose slider state through attributes, events, and the global API

Example:

<div data-rt-slider data-rt-list=".cms-list" data-rt-item=".cms-item">
  <div class="cms-list">
    <div class="cms-item">Slide 1</div>
    <div class="cms-item">Slide 2</div>
    <div class="cms-item">Slide 3</div>
  </div>
</div>

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-slider@latest/dist/index.min.js"></script>

Note: If you do not provide data-rt-list and data-rt-item, the slider will not initialize.

3. Activation Rules

The library activates when all of the following are true:

• An element with the attribute data-rt-slider is found in the DOM.
• The required data-rt-list and data-rt-item selectors are present on that container.
• The data-rt-list selector resolves to a valid element within that container.

If these conditions are met, the library initializes the instance automatically.

4. Configuration (HTML Attributes)

Basic Setup

<div data-rt-slider data-rt-list=".list-class" data-rt-item=".item-class">
  ...
</div>

UI Controls (Optional)

<div
  data-rt-slider
  data-rt-btn-prev=".prev-button"
  data-rt-btn-next=".next-button"
  data-rt-scroll-bar=".custom-scrollbar"
  data-rt-scroll-track=".custom-track"
>
  ...
</div>

Core Attributes (Selectors)

| Attribute | Description | Required | | ----------------------- | ---------------------------------------------------------- | -------- | | data-rt-slider | Activates the slider instance | Yes | | data-rt-slider-id | Optional identifier (auto-generated if missing) | No | | data-rt-list | Selector for the scrollable wrapper | Yes | | data-rt-item | Selector for individual slides | Yes | | data-rt-spacer | Selector/Class for edge spacers (padding) | No | | data-rt-btn-prev | Selector for "Previous" button | No | | data-rt-btn-next | Selector for "Next" button | No | | data-rt-scroll-track | Selector for custom scrollbar track | No | | data-rt-scroll-bar | Selector for custom scrollbar thumb | No | | data-rt-margin-ref | Selector used to align slide anchors to a layout reference | No | | data-rt-overlay-start | Selector for the leading edge overlay | No | | data-rt-overlay-end | Selector for the trailing edge overlay | No |

Physics & Behavior Configuration

These attributes control the Lenis instance used on desktop.

<div
  data-rt-slider
  data-rt-slider-lerp="0.1"
  data-rt-slider-infinite="false"
></div>

| Attribute | Description | Default | | ------------------------------------ | -------------------------------------- | ------------- | | data-rt-slider-lerp | Inertia interpolation (lower = slower) | Lenis default | | data-rt-slider-duration | Scroll duration (alt to lerp) | Lenis default | | data-rt-slider-easing | Easing function (e.g., easeOutExpo) | Lenis default | | data-rt-slider-orientation | Scroll orientation | horizontal | | data-rt-slider-gesture-orientation | Gesture orientation | horizontal | | data-rt-slider-smooth-wheel | Enable mouse wheel smoothing | true | | data-rt-slider-wheel-multiplier | Multiplier for wheel-based scrolling | Lenis default | | data-rt-slider-touch-multiplier | Multiplier for touch-based scrolling | Lenis default | | data-rt-slider-infinite | Infinite scrolling | false | | data-rt-slider-auto-resize | Recalculate on window resize | true |

Advanced JSON Options

<div
  data-rt-slider
  data-rt-slider-options-json='{"lerp":0.05, "wheelMultiplier": 2}'
></div>

Used to pass complex configuration objects directly to the underlying Lenis instance.

Slide State Output

As the slider moves, rt-slider writes state back to the DOM automatically.

Root attributes

| Attribute | Description | | ----------------------------------------- | ------------------------------------------ | | data-rt-slider-active-index | Current nearest active slide index | | data-rt-slider-from-index | Current segment start slide index | | data-rt-slider-to-index | Current segment end slide index | | data-rt-slider-segment-progress | Current segment progress from 0 to 1 | | data-rt-slider-segment-progress-percent | Current segment progress from 0 to 100 | | data-rt-slider-scroll-current | Current clamped horizontal scroll position | | data-rt-slider-scroll-max | Maximum horizontal scroll position | | data-rt-slider-scroll-progress | Overall slider progress from 0 to 1 | | data-rt-slider-scroll-progress-percent | Overall slider progress from 0 to 100 | | data-rt-slider-scroll-direction | forward, backward, or none | | data-rt-slider-scroll-at-start | true when the slider is at the start | | data-rt-slider-scroll-at-end | true when the slider is at the end |

Per-item attributes

| Attribute | Description | | --------------------------------------------- | -------------------------------------------------------------------------- | | data-rt-slider-item-index | Slide index | | data-rt-slider-item-active | true when this item is the active slide | | data-rt-slider-item-from | true when this item is the current segment start | | data-rt-slider-item-to | true when this item is the current segment end | | data-rt-slider-item-previous | true when this item is immediately before the active slide | | data-rt-slider-item-next | true when this item is immediately after the active slide | | data-rt-slider-item-before-active | true when this item is before the active slide | | data-rt-slider-item-after-active | true when this item is after the active slide | | data-rt-slider-item-anchor-progress | This slide's anchor position from 0 to 1 | | data-rt-slider-item-anchor-progress-percent | This slide's anchor position from 0 to 100 | | data-rt-slider-item-distance | Distance in pixels from the current scroll position to this slide's anchor |

These attributes are useful for CSS-driven animations, slide-aware UI, progress indicators, edge-aware controls, and syncing other interface elements to the slider.

Custom Events

Each slider instance dispatches events from the root element.

| Event | Description | | ------------------- | ------------------------------------------- | | rtSlider:progress | Fires when computed scroll progress changes | | rtSlider:slide | Fires when the computed slide state changes | | rtSlider:active | Fires when the active slide index changes |

Example:

const slider = document.querySelector("[data-rt-slider]");

slider.addEventListener("rtSlider:progress", function (event) {
  console.log("Progress:", event.detail.progress);
});

slider.addEventListener("rtSlider:slide", function (event) {
  console.log(event.detail);
});

slider.addEventListener("rtSlider:active", function (event) {
  console.log("Active slide:", event.detail.active.index);
});

rtSlider:progress includes a cloned scroll-state object in event.detail.

rtSlider:slide and rtSlider:active include a full cloned slide-state object in event.detail.

Dependency Loader Overrides

The library automatically loads Lenis from a CDN if not present. You can rely on the default or load your own version before rt-slider.

| Attribute | Description | | ----------------------------- | --------------------------------------------------- | | data-rt-slider-lenis="true" | Add this to a script tag to identify external Lenis |

5. Multiple Instances

rt-slider supports multiple independent instances on the same page.

Each instance:

• Has its own independent scroll physics
• Calculates its own progress bars and button states
• Tracks its own active slide, segment state, and overall scroll progress
• Dispatches its own custom events
• Is registered internally with a unique ID

6. Global API

Once initialized:

window.rtSlider;

Common Methods

| Method | Description | | -------------------- | ---------------------------------------------------- | | ids() | Returns an array of active slider IDs | | get(id) | Returns the slider instance object | | getSlideState(id) | Returns a cloned slide-state object for an instance | | getScrollState(id) | Returns a cloned scroll-state object for an instance | | getProgress(id) | Returns overall slider progress from 0 to 1 | | refresh() | Forces a recalculation of layout (all instances) | | destroy(id?) | Destroys specific instance or all if no ID given |

Example usage:

// Refresh layout after an AJAX load
window.rtSlider.refresh();

// Get computed state
const ids = window.rtSlider.ids();
const firstSliderSlideState = window.rtSlider.getSlideState(ids[0]);
const firstSliderScrollState = window.rtSlider.getScrollState(ids[0]);
const firstSliderProgress = window.rtSlider.getProgress(ids[0]);

// Destroy a specific slider
window.rtSlider.destroy("my-slider-id");

Instance Helpers

When using window.rtSlider.get(id), each instance also exposes helper methods:

| Method | Description | | -------------------- | ------------------------------------------------------ | | getSlideState() | Returns a cloned slide-state object for that instance | | getScrollState() | Returns a cloned scroll-state object for that instance | | getProgress() | Returns overall slider progress from 0 to 1 | | getActiveIndex() | Returns the current active slide index | | getActiveElement() | Returns the current active slide element |

7. Console Logging

rt-slider operates silently by default.

It does not rely on console output during normal use. If initialization fails, the most common causes are invalid selectors, missing required attributes, or invalid external configuration.

8. Troubleshooting

Slider not initializing

• Ensure data-rt-slider is present on the parent.
• Crucial: Ensure data-rt-list and data-rt-item attributes match valid elements inside the container.
• Ensure the data-rt-list selector resolves successfully inside the slider root.

Buttons not working

• Ensure the selectors in data-rt-btn-prev and data-rt-btn-next match your button elements.
• If buttons are outside the slider container, give them the attribute data-rt-slider-for="slider-id".

Scrollbar not moving

• Ensure data-rt-scroll-track and data-rt-scroll-bar are set correctly.
• The "bar" should be inside the "track" for the cleanest result, though the logic handles positioning independently.

Slide state attributes not updating

• Ensure the slider is actually scrollable. If content does not overflow horizontally, active state will still resolve, but progress and movement-driven changes will be limited.
• Ensure data-rt-item matches the actual slide elements and not a wrapper around them.

Progress not reaching 1 at the end

• rt-slider uses edge-aware scroll detection and clamps progress to 1 when the visible viewport reaches the end of the slider.
• If you are building custom progress indicators, use window.rtSlider.getProgress(id), window.rtSlider.getScrollState(id), or the rtSlider:progress event instead of deriving progress manually from raw DOM measurements.

Custom events not firing as expected

• rtSlider:progress fires when computed scroll progress changes.
• rtSlider:slide fires when computed slide state changes.
• rtSlider:active fires when the active slide changes.
• All events are dispatched from the element with data-rt-slider, not from the list or item elements.

9. License

MIT License

Package: @rethink-js/rt-slider GitHub: https://github.com/Rethink-JS/rt-slider

by Rethink JS https://github.com/Rethink-JS