🧈 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! 🧈✨