@maxweek/react-scroller NPM

React-scroller

Make your blocks scrolling easy, with a custom scroll-bar, based on native browser scroll. It is for simple and progressive applications, works on all modern browsers. It has a minimal load on the system, and has maximum performance, expandable and updatable

Features

Default scroll
Horizontal scroll
Vertical scroll
Both vertical and horizontal scroll
Grab content
Grab cursor
Interactive scrollbar
Variation of scrollbar positions
Trackpad detecting
Border padding and fading
Horizontal scroll by mouse wheel
Minimal processing
Based on original browser scroll
Extendable
Auto updating on child changes
Base Events
Base Methods
Ref with methods and properties (with interface)
Observing self size and reiniting automatically

Todo

Base scroll
Horizontal scroll
Vertical scroll
Both vertical and horizontal scroll
Grab content
Grab cursors and other visual features
Class extending
Base Methods
Base Events
Required styles
Trackpad detect
ResizeObserver
Scrolling Duration
More Methods
More Events
Inertia (custom scroll engine)

Installation

npm i @maxweek/react-scroller

First Usage

import Scroller from "@maxweek/react-scroller";
import "@maxweek/react-scroller/css";

const YourComponent = () => (
  <Scroller>
    {/* Your content */}
  </Scroller>
);

Usage

import Scroller, { IScrollerRef, IScroller, IScrollerProperties } from "@maxweek/react-scroller";
import "@maxweek/react-scroller/css";
import { useRef } from "react";

const YourComponent = () => {
  // Ref
  const scrollerRef = useRef<IScrollerRef>(null);

  // Methods
  const scrollToStart = () => {
    scrollerRef.current?.scrollToStart(); // scroll to start
  };
  const scrollToEnd = () => {
    scrollerRef.current?.scrollToEnd(); // scroll to end
  };
  const scrollTo = () => {
    scrollerRef.current?.scrollTo(100); // scroll to 100px
  };
  const update = () => {
    scrollerRef.current?.update(); // update scroll calculations
  };
  const getScrollerRef = () => {
    let ref = scrollerRef.current?.scrollRef; // get ref of main scroller box to control manually
  };
  const getProperties = () => {
    if (!scrollerRef.current) return;
    let properties: IScrollerProperties = scrollerRef.current?.getProperties(); // get properties of scroller object
  };

  // Scroller
  return (
    <Scroller
      ref={scrollerRef}
      needBar={true}
      barAltPosition={false}
      vertical={true}
      horizontal={true}
      grab={true}
      borderFade={true}
      autoHide={false}
      borderPadding={true}
      grabCursor={true}
      showWhenMinimal={true}
      className={'your-scroller-class'}
      barClassName={'your-scroller-bar-class'}
      barRollerClassName={'your-scroller-bar-roller-class'}
      contentClassName={'your-scroller-content-class'}
      onScroll={(x, y) => console.log(`scroll progress x: ${x.progress}, y: ${y.progress}`)}
      onReachStart={(type) => console.log(`reach start ${type}`)}
      onReachEnd={(type) => console.log(`reach end ${type}`)}
    >
      {/* Your content */}
    </Scroller>
  );
};

Full usage you can see on https://github.com/maxweek/react-scroller

Props

import { IScroller } from "@maxweek/react-scroller";
import "@maxweek/react-scroller/css";

const props: Partial<IScroller> = {
  needBar: true,
  barAltPosition: false,
  vertical: true,
  horizontal: true,
  grab: true,
  autoHide: false,
  borderFade: true,
  borderPadding: true,
  grabCursor: true,
  showWhenMinimal: true,
  className: 'your-scroller-class',
  barClassName: 'your-scroller-bar-class',
  barRollerClassName: 'your-scroller-bar-roller-class',
  contentClassName: 'your-scroller-content-class',
  onScroll: (x, y) => console.log(`scroll progress x: ${x.progress}, y: ${y.progress}`),
  onReachStart: (type) => console.log(`reach start ${type}`),
  onReachEnd: (type) => console.log(`reach end ${type}`)
};

Configuration

vertical: Enables vertical scrolling. Default is false.
horizontal: Enables horizontal scrolling. Default is false.
both: Enables both vertical and horizontal scrolling. Default is false.

const config = {
  // ...existing config options...
  vertical: true, // Enable vertical scrolling
  horizontal: true, // Enable horizontal scrolling
  both: true, // Enable both axis scrolling
};

Methods

import { IScrollerRef, IScroller, IScrollerProperties } from "@maxweek/react-scroller";
import { useRef } from "react";

const scrollerRef = useRef<IScrollerRef>(null);

// Methods
const scrollToStart = () => {
  scrollerRef.current?.scrollToStart(2000); // scroll to start
};
const scrollToEnd = () => {
  scrollerRef.current?.scrollToEnd(2000); // scroll to end
};
const scrollTo = () => {
  scrollerRef.current?.scrollTo(100, 2000); // scroll to 100px
};
const update = () => {
  scrollerRef.current?.update(); // update scroll calculations
};
const getScrollerRef = () => {
  let ref = scrollerRef.current?.scrollRef; // get ref of main scroller box to control manually
};
const getProperties = () => {
  if (!scrollerRef.current) return;
  let properties: IScrollerProperties = scrollerRef.current?.getProperties(); // get properties of scroller object
};

Your issues on GitHub

GitHub: https://github.com/maxweek/react-scroller

Thank you for using my package!

Max Nedelko 2024