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

Todo

• Base scroll
• Horizonal scroll
• Grab content
• Grab cursors and other visual features
• Class extending
• Base Methods
• Base Events
• More Methods
• More Events
• Inertia (custom scroll engine)

Installation

npm i @maxweek/react-scroller

First Usage

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

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

Usage

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

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}
    borderPadding={true}
    grabCursor={true}
    className={'your-scroller-class'}
    barClassName={'your-scroller-bar-class'}
    barRollerClassName={'your-scroller-bar-roller-class'}
    contentClassName={'your-scroller-content-class'}
    onScroll={() => console.log('reach end')}
    onReachStart={() => console.log('reach start')}
    onReachEnd={() => console.log('scroll')}
  >
    {/* Your content */}
  </Scroller>
}

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

Props

  import { IScroller } from "./scroller/scroller"

  const props: Partial<IScroller> = {
    needBar: true,
    barAltPosition: true,
    horizontal: true,
    grab: true,
    borderFade: true,
    borderPadding: true,
    grabCursor: true,
    className: 'your-scroller-class',
    barClassName: 'your-scroller-bar-class',
    barRollerClassName: 'your-scroller-bar-roller-class',
    contentClassName: 'your-scroller-content-class',
    onScroll: () => console.log('reach end'),
    onReachStart: () => console.log('reach start'),
    onReachEnd: () => console.log('scroll'),
  }

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	add fadding in directions of scroll by masking
borderPadding?	boolean	false	add padding in directions of scroll
grabCursor?	boolean	false	enables grab cursor on hover
className?	string	''	class for scroller box
barClassName?	string	''	class for scrollbar
barRollerClassName?	string	''	class for scrollbar roller
contentClassName?	string	''	class for content wrapper
onScroll?	event	() => {}	Event on 'scroll'
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()          // 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
  }

License

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

More

Your issues on github

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

Thank you for using my package!

Max Nedelko 2024