@maxweek/react-scroller

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
• 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

• [x] Base scroll
• [x] Horizonal scroll
• [x] Grab content
• [x] Grab cursors and other visual features
• [x] Class extending
• [x] Base Methods
• [x] Base Events
• [x] Required styles
• [x] Trackpad detect
• [x] ResizeObserver
• [x] 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, Scroller, IScroller, IScrollerProperties } from "@maxweek/react-scroller";
import "@maxweek/react-scroller/css";

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 contol manualy
  }
  const getProperties = () => {
    if (!scrollerRef.current) return
    let properties: IScrollerProperties = scrollerRef.current?.getProperties() // get properties of scroller object
  }

  // Scroller
  <Scroller
    ref={scrollerRef}
    needBar={true}
    barAltPosition={false}
    horizontal={false}
    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={(progress: number, duration?: number) => console.log(`scroll progress ${progress}`)}
    onReachStart={(duration?: number) => console.log('reach start')}
    onReachEnd={(duration?: number) => console.log('reach end')}
  >
    {/* Your content */}
  </Scroller>
}

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

Props

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

  const props: Partial<IScroller> = {
    needBar: true,
    barAltPosition: false,
    horizontal: false,
    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={(progress: number) => console.log(`scroll progress ${progress}`)}
    onReachStart={() => console.log('reach start')}
    onReachEnd={() => console.log('reach end')}
  }

PropName	Type	Default	Description
children	ReactNode		React child
ref?	IScrollerRef		Ref to control the element
needBar?	boolean	false	Enables scrollbar
barAltPosition?	boolean	false	Changes scrollbar position, default at right - changes to left, when horizontal enabled - changes bottom to top
horizontal?	boolean	false	Makes your box scrolling horizontal
grab?	boolean	false	Enables grabbing your scroll content
borderFade?	boolean	false	Addes fadding in directions of scroll by masking
borderPadding?	boolean	false	Addes padding in directions of scroll
autoHide?	boolean	false	Hides scrollbar if it is not hovered
grabCursor?	boolean	false	Enables grab cursor on hover
showWhenMinimal??	boolean	true	enables bar on hover, when the scroll height smaller than box height
className?	string	''	CSS Class for scroller box
barClassName?	string	''	CSS Class for scrollbar
barRollerClassName?	string	''	CSS Class for scrollbar roller
contentClassName?	string	''	CSS Class for content wrapper
onScroll?	event	(progress: number) => {}	Event on 'scroll', `progress` prop is the interpolation of scroll progress from 0 to 1
onReachStart?	event	() => {}	Event on 'scroll' reaches start
onReachEnd?	event	() => {}	Event on 'scroll' reaches end

Methods

  import { IScrollerRef, Scroller, IScroller, IScrollerProperties } from "./scroller/scroller"

  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 contol manualy
  }
  const getProperties = () => {
    if (!scrollerRef.current) return
    let properties: IScrollerProperties = scrollerRef.current?.getProperties() // get properties of scroller object
  }

More

Your issues on github

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

Thank you for using my package!

Max Nedelko 2024

Keywords

"touch", "scrollbar", "horizontal", "scroller", "scroll", "react"

License

• React Scroll is licensed under the MIT License. Explore this to understand terms and conditions of the license- https://opensource.org/licenses/MIT