react-scroll-kit

Router-aware scroll management for React applications.

Automatic scroll restoration, navigation-aware scrolling, reusable hooks, utilities, and optional UI components for React Router apps.

Features

• Router-aware scroll management
• Automatic scroll restoration
• Reading progress bar
• Smooth scrolling utilities
• Scroll-to-top button
• Infinite scrolling hooks
• Scroll direction detection
• Scroll spy support
• IntersectionObserver utilities
• Container-aware scrolling support
• Reduced motion accessibility support
• SSR safe
• Lightweight and tree-shakeable

Installation

Install package and peer dependencies:

npm install react-scroll-kit react react-router-dom

Using yarn:

yarn add react-scroll-kit react react-router-dom

Using pnpm:

pnpm add react-scroll-kit react react-router-dom

Quick Start

Place ScrollToTop inside your React Router application.

import { ScrollToTop } from 'react-scroll-kit';

function App() {
  return (
    <>
      <ScrollToTop />
      {routes}
    </>
  );
}

Utilities API

scrollTo

Programmatically scroll the page or a custom container.

import { scrollTo } from 'react-scroll-kit';

scrollTo('#contact', {
  behavior:'smooth',
  duration:700,
  easing:'easeOutExpo',
  offset:80
});

Options

| Option | Type | Default | |---|---:|---:| | behavior | smooth | instant | instant | | duration | number | 500 | | easing | string | function | easeOutQuad | | offset | number | 0 | | delay | number | 0 | | scrollAxis | x | y | both | y | | container | HTMLElement | RefObject | window | | respectReducedMotion | boolean | true |

hashScroll

Smoothly scroll to URL hash elements.

import { hashScroll } from 'react-scroll-kit';

hashScroll('#pricing');

lockScroll / unlockScroll

Lock scrolling during modals or overlays.

import {
 lockScroll,
 unlockScroll
} from 'react-scroll-kit';

lockScroll();

unlockScroll();

Components

ScrollToTop

Automatically scroll to top on route changes.

<ScrollToTop
 behavior="smooth"
 duration={700}
 easing="easeOutExpo"
 excludeRoutes={['/exclusive']}
/>

Props:

| Prop | Type | Default | |---|---:|---:| | behavior | smooth | instant | instant | | duration | number | 500 | | easing | string | function | easeOutQuad | | delay | number | 0 | | scrollAxis | x | y | both | y | | container | HTMLElement | RefObject | window | | excludeRoutes | string[] | [] | | respectReducedMotion | boolean | true |

ScrollRestoration

Restore previous page positions.

<ScrollRestoration
 storageKey="app-scroll"
 container={contentRef}
/>

ScrollProgressBar

Show page reading progress.

<ScrollProgressBar
 height={4}
 color="linear-gradient(to right,#3b82f6,#10b981)"
 position="bottom"
 container={contentRef}
/>

Props:

| Prop | Type | Default | |---|---:|---:| | height | string | number | 3 | | color | string | #1565C0 | | zIndex | number | 9999 | | position | top | bottom | top | | container | HTMLElement | RefObject | window |

ScrollToTopButton

Display a floating button after scrolling.

<ScrollToTopButton
 threshold={400}
/>

ScrollLink

Navigation-aware scroll links.

<ScrollLink
 to="/about#pricing"
 scrollTo="#pricing"
 scrollBehavior="smooth"
>
 Go to pricing
</ScrollLink>

Scrollable Container Example

If your app uses:

overflow-y:auto

pass the container reference.

import { useRef } from 'react';

const contentRef = useRef(null);

return (
<>
   <ScrollProgressBar
      container={contentRef}
   />

   <ScrollToTop
      container={contentRef}
   />

   <main
      ref={contentRef}
      style={{
        height:'100vh',
        overflowY:'auto'
      }}
   >
      {children}
   </main>
</>
)

Hooks

useScrollPosition

import {
 useScrollPosition
} from 'react-scroll-kit';

const {x,y} =
useScrollPosition();

useScrollDirection

import {
 useScrollDirection
} from 'react-scroll-kit';

const direction=
useScrollDirection({
 threshold:10
});

useScrolledPast

import {
 useScrolledPast
} from 'react-scroll-kit';

const visible=
useScrolledPast(300);

useInView

import {
 useInView
} from 'react-scroll-kit';

const {
 ref,
 inView
}=useInView({
 threshold:0.5
});

useScrollSpy

import {
 useScrollSpy
} from 'react-scroll-kit';

const active=
useScrollSpy([
 '#home',
 '#pricing',
 '#contact'
]);

useInfiniteScroll

import {
 useInfiniteScroll
} from 'react-scroll-kit';

const {
 loading,
 sentinelRef
}
=
useInfiniteScroll(
 async()=>{
   await loadMore();
 }
);

Accessibility

Supports:

• prefers-reduced-motion
• keyboard navigation
• passive event listeners
• requestAnimationFrame optimization

Example:

import {
 prefersReducedMotion
} from 'react-scroll-kit';

if(prefersReducedMotion()){
   // skip animations
}

FAQ

Progress bar does not move

If using:

overflow-y:auto

pass container reference:

<ScrollProgressBar
 container={contentRef}
/>

Hash scrolling does not work

For asynchronous rendering:

hashScroll('#target');

Scroll restoration resets position

Scroll restoration only triggers on browser back/forward navigation.

Performance

• Lightweight
• Tree-shakeable
• requestAnimationFrame optimized
• passive listeners
• SSR safe

Browser Support

• Chrome >= 90
• Firefox >= 88
• Safari >= 14
• Edge >= 90

Development

Clone repository:

git clone https://github.com/Coderkube-App/react-scroll-kit.git

cd react-scroll-kit

npm install

npm run build

License

MIT © Ammar Shaikh