react-neo-scrollbar-z

A customizable React scrollbar component built on top of Perfect Scrollbar, with plugin support and rich APIs.
Supports inertia scroll, load more, gradient indicators, highlight, spy, virtualization, and custom plugins.

---

---

🚀 Live Demo

👉 Codesandbox

---

✨ Features

• ⚡ Lightweight and smooth scrolling, built on top of Perfect Scrollbar
• 🎨 Fully customizable (size, height, width, direction, easing)
• 🔌 Plugin System
  • Inertia / Momentum scroll
  • ScrollSpy
  • Highlight item
  • Gradient indicators
  • Custom "Load More" support
  • Pull-to-refresh
  • Progress bar
  • Minimap
• 🛠 Exposed ref API for programmatic control
• 🔄 Many event callbacks for scroll control
• 🚀 Easy integration into lists, tables, dashboards
• 📊 Virtualization Support (render thousands of items smoothly, like react-window)

---

📦 Installation

npm install react-neo-scrollbar-z

---

🚀 Basic Usage

import "react-neo-scrollbar-z/build/styles.css";

import React, { useState, useEffect, useRef } from "react";
import Scrollbar, { loadMorePlugin, pullToRefreshPlugin } from "react-neo-scrollbar-z";
import type { IFScrollbarRefProps } from "react-neo-scrollbar-z";

export default function DemoApp() {
  const scrollbarRef = useRef<IFScrollbarRefProps>(null);
  const [posts, setPosts] = useState<any[]>([]);
  const [page, setPage] = useState(1);
  const [hasMore, setHasMore] = useState(true);

  useEffect(() => {
    const initial = Array.from({ length: 10 }, (_, i) => ({ id: i + 1, title: "Post " + (i+1) }));
    setPosts(initial);
  }, []);

  const handleRefresh = async () => {
    await new Promise(r => setTimeout(r, 1000));
    const newPost = { id: Date.now(), title: "Refreshed " + Date.now() };
    setPosts(prev => [newPost, ...prev]);
  };

  const handleLoadMore = async () => {
    if (!hasMore) return false;
    await new Promise(r => setTimeout(r, 1000));
    const nextId = posts.length + 1;
    const newPosts = Array.from({ length: 5 }, (_, i) => ({ id: nextId + i, title: "Loaded " + (nextId + i) }));
    setPosts(prev => [...prev, ...newPosts]);
    setPage(p => p + 1);
    if (page >= 3) { setHasMore(false); return false; }
    return true;
  };

  return (
    <Scrollbar
      ref={scrollbarRef}
      maxHeight={400}
      plugins={[
        // pullToRefreshPlugin({ onRefresh: handleRefresh }),
        // loadMorePlugin({ onLoadMore: handleLoadMore }),
      ]}
    >
      <ul>
        {posts.map(post => <li key={post.id}>{post.title}</li>)}
      </ul>
    </Scrollbar>
  );
}

---

📐 Props

Layout & Size

Prop	Type	Default	Description
width	string / number	—	Fixed width
height	string / number	—	Fixed height
maxWidth	string / number	—	Max width
maxHeight	string / number	—	Max height

Core Behavior

Prop	Type	Default	Description
id	string	—	Unique identifier
children	ReactNode	—	Content
style	CSSProperties	—	Custom styles
direction	"vertical" | "horizontal" | "both"	"vertical"	Scroll direction
always	boolean	false	Always show scrollbar
autoHide	boolean	true	Auto-hide scrollbar
disableKeyboard	boolean	false	Disable keyboard
wheelStop	boolean	false	Stop wheel propagation
scrollLock	boolean	false	Prevent body scroll

Scrolling & Effects

Prop	Type	Default	Description
inertia	boolean	false	Enable inertia
inertiaFriction	number	0.92	Friction factor
smoothScroll	boolean	true	Smooth animations
scrollDuration	number	300	Duration for programmatic scroll
scrollEasing	function	easeInOutQuad	Custom easing
autoScrollBottom	boolean	false	Auto-scroll bottom
autoScrollToNewItem	boolean	false	Auto-scroll new item
preserveScroll	boolean	false	Save/restore position
scrollSaveKey	string	—	Storage key
initialScroll	"top" | "bottom" | number	"top"	Initial scroll
triggerScrollClick	boolean	false	Click track to scroll

Plugins & Data

Prop	Type	Default	Description
plugins	IFScrollbarPlugin[]	[]	Attach plugins
effectData	unknown	—	Trigger re-render
options	PerfectScrollbar.Options	—	Native options
refScroll	MutableRefObject	—	Ref API

Events

Callback	Params	Description
onScroll	{x, y}	Fires on scroll
onScrollStart	—	Fires on start
onScrollStop	—	Fires on stop
onReachTop	—	Reached top
onReachBottom	—	Reached bottom
onReachLeft	—	Reached left
onReachRight	—	Reached right
onReachThreshold	percent: number	Threshold crossed
onOverflowChange	(x: boolean, y: boolean)	Overflow change

---

📚 Ref API

scrollToX(x: number, duration?: number, easing?: ScrollEasingFn)
scrollToY(y: number, duration?: number, easing?: ScrollEasingFn)
scrollToTop(duration?: number, easing?: ScrollEasingFn)
scrollToBottom(duration?: number, easing?: ScrollEasingFn)
scrollToIndex(index: number, duration?: number, easing?: ScrollEasingFn)
scrollToElement(el: HTMLElement, duration?: number, easing?: ScrollEasingFn)
scrollToPercent(yPercent: number, xPercent?: number, duration?: number, easing?: ScrollEasingFn)

update()
destroy()
getScrollbar()
getScrollElement()

---

🔌 Plugin Interface

export interface IFScrollbarPlugin {
  mountPosition?: "inside" | "outside" | "before";
  onInit?: (api: IFScrollbarRefProps, el: HTMLElement) => void;
  onScroll?: (el: HTMLElement) => void;
  onDestroy?: () => void;
  render?: () => React.ReactNode;

  onScrollStart?: (el: HTMLElement) => void;
  onScrollStop?: (el: HTMLElement) => void;
  onReachTop?: () => void;
  onReachBottom?: () => void;
  onReachLeft?: () => void;
  onReachRight?: () => void;
  onReachThreshold?: (percent: number) => void;
}

Built-in Plugins

• bounceEffectPlugin
• bounceHighlightPlugin
• gradientIndicatorPlugin
• highlightItemPlugin
• inertiaPlugin
• loadMorePlugin
• minimapPlugin
• pullToRefreshPlugin
• progressBarPlugin
• scrollSpyPlugin
• snapToItemPlugin

---

📊 Virtualization

VirtualList allows you to render tens of thousands of rows efficiently by only rendering visible items in the viewport.

---

📋 License

MIT