use-scrollsmoother
TypeScript icon, indicating that this package has built-in type declarations

1.2.6 • Public • Published

ScrollSmoother React Hook

Static Badge Static Badge

The useScrollSmoother React Hook provides a simple way to manage smooth scrolling behavior using the ScrollSmoother plugin from the GreenSock Animation Platform (GSAP). This hook enhances the scrolling experience by smoothly catching up to the native scroll position, applying effects to specified elements, and providing various configuration options.

Autocomplete, guides on hover and type definitions are available for the configs.

Installation

npm install use-scrollsmoother

Make sure you have club GSAP (shockingly or business), react and typescript installed. You can install it using npm (required dependency):

npm install gsap@npm:@gsap/shockingly
or
npm install ./gsap-bonus.tgz

Usage

import { useScrollSmoother } from 'use-scrollsmoother';

function YourApp() {
  const { smoothWrapperRef, smoothContentRef } = useScrollSmoother({
	  config: {
		  smooth: 1, // Time (in seconds) to catch up to the native scroll position
		  smoothTouch: false, // Enable scroll smoothing on touch devices
		  normalizeScroll: false, // Force scrolling on the JavaScript thread
		  snormalizescroll: false, // Force scrolling on the JavaScript thread
		  ignoreMobileResize: false, // Avoid triggering ScrollTrigger.refresh() on mobile resize
		  signoremobileresize: false, // Avoid triggering ScrollTrigger.refresh() on mobile resize
		  effects: false, // Apply effects based on data-speed and data-lag attributes
		  effectsPrefix: 'scroll-', // Custom prefix for effects data attributes
		  effectsPadding: 0, // Expand effects application to a specified number of pixels
		  ease: 'expo', // Easing function for smooth scrolling
		  onUpdate: () => {}, // Function to call after each smooth scroll update
		  onFocusIn: () => true, // Function to call when a new element receives focus
		  onStop: () => {}, // Function to call when smooth scrolling comes to a stop
	  },
  });

  return (
    <div ref={smoothWrapperRef}>
      <div ref={smoothContentRef}>
        {/* Your content goes here */}
      </div>
    </div>
  );
}

Notes

  • Ensure that the smoothWrapperRef and smoothContentRef are applied to the correct elements in your component and in the order as illustrated in the example above.
  • Make sure GSAP is properly installed and available in your project.
  • In my test usage snormalizescroll same as ScrollTrigger.normalizeScroll() and signoremobileresize same as ScrollTrigger.ignoreMobileResize() work better in mobile as compared to the normalizeScroll and ignoreMobileResize.

Feel free to adjust the configuration options to suit your specific use case. For more details on GSAP and ScrollSmoother, refer to the GSAP documentation.

Package Sidebar

Install

npm i use-scrollsmoother

Weekly Downloads

6

Version

1.2.6

License

ISC

Unpacked Size

29.3 kB

Total Files

7

Last publish

Collaborators

  • klevertopee