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
• Clear console logs for debugging and verification

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](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

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](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 any 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 resolve to valid elements 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 |

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) | 0.1 | | data-rt-slider-duration | Scroll duration (alt to lerp) | 1.2 | | data-rt-slider-easing | Easing function (e.g., easeOutExpo) | easeOutQuad | | data-rt-slider-orientation | Scroll orientation | horizontal | | data-rt-slider-smooth-wheel | Enable mouse wheel smoothing | true | | 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.

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-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.
• 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 | | 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();

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

7. Console Logging

rt-slider operates silently by default but provides warnings if:

• Required selectors (data-rt-list, data-rt-item) are missing.
• JSON configuration is invalid.
• Dependency loading fails.

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.

Buttons not working

• Ensure the selectors in data-rt-btn-prev 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" must be a child of the "track" in the DOM for standard styling, though the logic handles positioning.

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