🧈 ButterScroll React (butterscroll-react)

A buttery smooth scrolling solution for React applications.

---

🎉 A Huge Thanks to the react-custom-scrollbars Community!

butterscroll-react is built on top of react-custom-scrollbars, an amazing library that provides flexible and customizable scrollbars for React applications.

🙏 A big shoutout to:

• The original developer Malte Wessel (@malte-wessel)
• The maintainers and all contributors who have kept this project alive
• Everyone who has improved and shared their knowledge in the open-source community

This package wouldn’t be possible without the foundation laid by react-custom-scrollbars, and we appreciate all the effort that has gone into making scrolling in React smoother and more customizable! 🚀✨

---

🚀 Features

✔️ Smooth Physics-Based Scrolling
✔️ Customizable Damping & Friction
✔️ Supports Nested Scroll Containers
✔️ Simple Hook & Component API

---

📦 Installation

Install butterscroll-react via NPM or Yarn:

npm install butterscroll-react
# OR
yarn add butterscroll-react

---

🔥 Usage

1️⃣ Using the ButterScrollContainer Component

A plug-and-play solution for smooth scrolling.

import React from 'react';
import { ButterScrollContainer } from 'butterscroll-react';

export default function App() {
  return (
    <ButterScrollContainer options={{ damping: 0.1, friction: 0.15 }}>
      <div style={{ height: '200vh', padding: '1rem' }}>
        <h1>Butter Smooth Scrolling! 🧈</h1>
        <p>Experience the smoothness!</p>
      </div>
    </ButterScrollContainer>
  );
}

---

2️⃣ Using the useButterScroll Hook

For advanced control over existing react-custom-scrollbars instances.

import React, { useRef } from 'react';
import { Scrollbars } from 'react-custom-scrollbars';
import { useButterScroll } from 'butterscroll-react';

export default function CustomScrollComponent() {
  const scrollbarsRef = useRef(null);

  useButterScroll(scrollbarsRef, { damping: 0.1, friction: 0.2 });

  return (
    <Scrollbars ref={scrollbarsRef} style={{ height: '100vh', width: '100vw' }}>
      <div style={{ height: '200vh', padding: '1rem' }}>
        <h1>Custom Smooth Scroll 🏎️</h1>
      </div>
    </Scrollbars>
  );
}

---

⚙️ Options

Both ButterScrollContainer and useButterScroll accept the following options:

Option	Type	Default	Description
damping	number	0.1	Controls scroll acceleration. Higher values make it more sensitive.
friction	number	0.15	Reduces velocity over time, controlling how fast scrolling slows down.
deltaLimit	number	0.5	Minimum scroll velocity before stopping.

---

🏗 Handling Nested Scroll Containers

If a ButterScrollContainer is inside another, the inner one prevents the outer one from scrolling when active.

<ButterScrollContainer options={{ damping: 0.08, friction: 0.12 }}>
  <div style={{ height: '300vh', padding: '1rem', background: '#f4f4f4' }}>
    <h1>Outer Scroll</h1>

    <div style={{ height: '300px', overflow: 'hidden', border: '1px solid black' }}>
      <ButterScrollContainer options={{ damping: 0.1, friction: 0.2 }}>
        <div style={{ height: '500px', padding: '1rem', background: '#ddd' }}>
          <h2>Inner Scroll</h2>
        </div>
      </ButterScrollContainer>
    </div>

  </div>
</ButterScrollContainer>

---

🛠 Development & Contributions

If you’d like to contribute, feel free to fork the repo and submit a PR.

📌 GitHub Repository:
🔗 GitHub - KoushikEng/butterscroll-react

git clone https://github.com/KoushikEng/butterscroll-react.git
cd butterscroll-react
npm install
npm run build

---

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

💡 Enjoy the buttery smooth scrolling experience! 🧈✨