react-smooth-scrollbar-z

react-smooth-scrollbar-z

• A modern, fully customizable React scrollbar library featuring NeoScrollbar and Scrollbar components
• Powered by Smooth Scrollbar – smooth, flexible, and plugin-ready.

---

---

Live Demo

Codesandbox

---

Features

• NeoScrollbar: Lightweight, sleek, and smooth scrollbar for basic use.

• Scrollbar: Advanced, fully-featured scrollbar with hover scaling, always-visible option, and full plugin support.

• Smooth & Responsive: Natural inertia and momentum scrolling for a polished user experience.

• Fully Customizable: Configure thumb color, size, hover scale, track color, opacity, and more.

• Dynamic Plugin System: Supports plugins like FadeScroll, HighlightItem, GradientIndicator, ScrollBlur, OverscrollGlow, BounceEffect, and others.

• Lazy Plugin Loading: Plugins are loaded on-demand for optimal performance.

• React Integration: React hooks (useNeoScrollbar) and refs provide full programmatic control (scroll to top, bottom, or any position).

• SSR-Safe: Works seamlessly in server-side rendered applications.

• Optimized for Modern React: Ready for React >=3.0.0 (AI-suggested best practices).

---

Installation

npm install react-smooth-scrollbar-z

---

Quick Example

import React, { useRef } from "react";
import { NeoScrollbar } from "react-smooth-scrollbar-z";

function App() {
  const scrollRef = useRef(null);

  return (
    <NeoScrollbar
      ref={scrollRef}
      height="300px"
      thumbColor="rgba(0,0,0,0.3)"
      thumbHoverColor="rgba(0,0,0,0.7)"
      showOnHover
    >
      <div style={{ height: "1000px" }}>Scrollable Content Here</div>
    </NeoScrollbar>
  );
}

Plugins

import React, { useRef } from "react";
import { NeoScrollbar, Scrollbar } from "react-smooth-scrollbar-z";
import {
  GradientIndicatorPlugin,
  HighlightItemPlugin,
  ScrollBlurPlugin,
} from "react-smooth-scrollbar-z";

import type { IFScrollbarHandle, IFNeoScrollbarHandle } from "react-smooth-scrollbar-z";

const content = Array.from({ length: 50 }, (_, i) => (
  <div
    key={i}
    className="item"
    style={{
      padding: "10px",
      borderBottom: "1px solid #ccc",
      background: i % 2 === 0 ? "#f5f5f5" : "#fff",
    }}
  >
    Item {i + 1}
  </div>
));

function AppScrollbar() {
  const neoRef = useRef<IFNeoScrollbarHandle>(null);
  const fullRef = useRef<IFScrollbarHandle>(null);

  return (
    <div style={{ padding: "20px", fontFamily: "sans-serif" }}>
      <div style={{ display: "flex", gap: "40px" }}>
        <div style={{ flex: 1 }}>
          <div style={{ marginBottom: "10px" }}>
            <button onClick={() => neoRef.current?.scrollToTop?.()}>Scroll Top</button>
            <button onClick={() => neoRef.current?.scrollToBottom?.()} style={{ marginLeft: 10 }}>
              Scroll Bottom
            </button>
          </div>
          <NeoScrollbar
            ref={neoRef}
            height="300px"
            thumbColor="rgba(0,0,0,0.3)"
            thumbHoverColor="rgba(0,0,0,0.7)"
            thumbSize="10px"
            showOnHover
            alwaysShowTracks
            trackColor="transparent"
            visibleOpacity={0.8}
            plugins={{
              scrollBlur: { blurAmount: 5, duration: 300, zIndex: 1000 },
            }}

            pluginLoaders={{
              scrollBlur: () => Promise.resolve(ScrollBlurPlugin),
            }}
          >
            {content}
          </NeoScrollbar>
        </div>

        <div style={{ flex: 1 }}>
          <div style={{ marginBottom: "10px" }}>
            <button onClick={() => fullRef.current?.scrollToTop?.()}>Scroll Top</button>
            <button onClick={() => fullRef.current?.scrollToBottom?.()} style={{ marginLeft: 10 }}>
              Scroll Bottom
            </button>
          </div>
          <Scrollbar
            ref={fullRef}
            height="300px"
            thumbColor="rgba(0,0,0,0.3)"
            thumbHoverColor="rgba(0,0,0,0.7)"
            thumbSize="12px"
            trackSize="12px"
            thumbHoverSize={16}
            showOnHover
            visibleOpacity={0.8}

            plugins={{
              highlightItem: { selector: ".item", className: "highlighted", mode: "center" },
              gradientIndicator: {
                height: 30,                  
                color: "rgba(0,0,0,0.2)",   
                fadeDuration: 300,          
              }
            }}

            pluginLoaders={{
              highlightItem: () => Promise.resolve(HighlightItemPlugin),
              gradientIndicator: () => Promise.resolve(GradientIndicatorPlugin),
            }}
          >
            {content}
          </Scrollbar>
        </div>
      </div>
    </div>
  );
}

export default AppScrollbar;

Hooks

useFullScrollbar(options) – returns { ref, initScrollbar, api } // Scrollbar

useNeoScrollbar(options) – returns { ref, api }

---

Props

Common Props

Prop	Type	Default	Description
height	string	"auto"	Scroll container height
width	string	"auto"	Scroll container width
thumbColor	string	"rgba(0,0,0,0.4)"	Scroll thumb color
trackColor	string	"transparent"	Scroll track color
thumbSize	string	"6px"	Scroll thumb size
thickness	number	6	Scrollbar thickness (Scrollbar)
thumbHoverColor	string	"rgba(0,0,0,0.6)"	Hover color for thumb
thumbHoverSize	`number	string`	undefined	Scale on hover (Scrollbar)
showOnHover	boolean	false	Track visible only on hover
visibleOpacity	number	1	Track opacity (0→1)
plugins	object	{}	SmoothScrollbar plugins object

API (via ref)

• scrollTo(x: number, y: number, duration?: number)
• scrollToTop(duration?: number)
• scrollToBottom(duration?: number)
• scrollBy(dx: number, dy: number, duration?: number) (Scrollbar)
• update()
• destroy()
• getScrollbar(): Scrollbar | null (Scrollbar)
• disableScroll() / enableScroll() (Scrollbar)
• setSpeed(multiplier: number) (Scrollbar)
• etc...

---

Plugins

Available plugins (can be used with Scrollbar via plugins prop):

• overscroll - bounce/glow effect
• edgeEasing
• resize
• anchor
• minimap
• fadeScroll
• scrollHint
• etc... see pluginLoaders

Usage:

---

License

MIT