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