React Overflow Slider

A lightweight, high-performance, and responsive horizontal slider for React that works smoothly across devices, including mobile touch and MacBook touchpads. It leverages native CSS overflow-x: auto for buttery-smooth scrolling, while providing custom navigation buttons for seamless user interaction.

🔗 Links

• 📦 View on NPM
• 💻 GitHub Repository
• 🌐 Live Demo

✨ Features

• 🚀 Smooth and Native Scrolling — No JS calculations during scroll, even on touch devices.
• 🎯 Customizable — Add your own navigation buttons and styles.
• 📱 Responsive Design — Fully adapts to different screen sizes.
• 🔥 Supports Any Content — Text, images, or custom HTML elements.
• ⚡ Zero Lag — Perfect for mobile swipes and MacBook touchpads.
• 🔍 Initial Scroll Position — Set a specific element to be visible on initialization.

📦 Installation

Using npm

npm install react-overflow-slider

Using yarn

yarn add react-overflow-slider

Using pnpm

pnpm add react-overflow-slider

🚀 Quick Start

import { OverflowSlider } from 'react-overflow-slider';
import 'react-overflow-slider/dist/index.css'; // Import styles for the slider

const Example = () => {
  return (
    <OverflowSlider>
      <div>Slide 1</div>
      <div>Slide 2</div>
      <div>Slide 3</div>
    </OverflowSlider>
  );
};

⚙️ Props

Prop	Type	Default	Description
children	ReactNode[]	—	Required. Child elements to display inside the slider.
prevButton	ReactNode	—	Custom "Previous" button.
nextButton	ReactNode	—	Custom "Next" button.
gap	number | string	0	Gap between elements inside the slider. You can use a number (for pixel values) or a CSS string (e.g., '4px', '1em') for the value.
duration	number	300	Scroll animation duration in milliseconds.

🧩 Advanced Features

📍 Scroll to a Specific Item on Mount

To make the slider automatically scroll to a specific item when it mounts, add the attribute data-first-visible="true" to any item or its child inside the slider:

<OverflowSlider>
  {tags.map(({ text, ...styles }) => (
    <div 
      key={text} 
      className="tag-item" 
      style={{ ...styles }}
      {
        // 🔥 Scroll to this item on mount
        ...(text === "Featured Item" && { "data-first-visible": "true" })
      }
    >
      {text}
    </div>
  ))}
</OverflowSlider>

🔄 The slider will automatically scroll to position the marked item at the start of the visible area on first render.

📋 Examples

🔤 Text Slider

A simple text slider with dynamic tag sizes.

⚠️ Note: When using fonts with fractional widths, rounding issues may occur, causing scroll glitches. For consistent behavior across platforms, use universal fonts (e.g., system-native fonts, sans-serif).

💡 Tip: To use custom fonts while avoiding these issues, apply a transparent sans-serif font to set the correct element width, and overlay your desired font using absolute positioning. This way, the invisible font defines the size, while the visible text uses the custom font.

https://github.com/iscars/react-overflow-slider/tree/main/src/examples/tag-slider

---

🖼️ Image Slider

A clean image slider for showcasing images.

https://github.com/iscars/react-overflow-slider/tree/main/src/examples/image-slider

---

📇 Custom HTML Slider

A flexible slider for showcasing any custom HTML elements, demonstrated here with cards featuring titles and descriptions.

https://github.com/iscars/react-overflow-slider/tree/main/src/examples/card-slider

🛠️ Development

To begin local development:

1. Clone the repo:

git clone https://github.com/iscars/react-overflow-slider.git

2. Install dependencies:

pnpm install

3. Run the project:

pnpm dev

📄 License

This project is licensed under the MIT License.
Feel free to use, modify, and distribute it as per the license terms. 🤝