CrystalScrollSmoother

Buttery-smooth scrolling with GSAP ScrollSmoother

Smooth Scrolling

Transforms native scroll into buttery-smooth momentum-based scrolling with configurable smoothing factor.

Parallax Effects

Add data-speed to any child element for parallax movement.

Responsive

Desktop-only by default. Falls back to native scroll on mobile for optimal touch experience.

Accessible

Respects prefers-reduced-motion and disables smooth scroll when enabled.

Basic Usage

Layout Integration

import { CrystalScrollSmoother } from '@artasce/crystal-ui';

export default function Layout({ children }) {
  return (
    <>
      {/* Fixed elements go OUTSIDE the smoother */}
      <Header />

      <CrystalScrollSmoother>
        <main>{children}</main>
      </CrystalScrollSmoother>

      <Footer />
    </>
  );
}

Parallax Effects

data-speed Attribute

{/* Inside CrystalScrollSmoother */}
<div data-speed="0.5">
  Moves at half scroll speed (appears to recede)
</div>

<div data-speed="1">
  Moves at normal speed (default)
</div>

<div data-speed="1.5">
  Moves 1.5x faster (appears to come forward)
</div>

<div data-lag="0.5">
  Lags behind scroll position (smooth follow)
</div>

Props

Prop	Type	Default	Description
smooth	number	1.5	Smoothing factor (higher = smoother)
effects	boolean	true	Enable data-speed parallax
desktopOnly	boolean	true	Only smooth scroll on desktop
breakpoint	number	768	Desktop detection breakpoint (px)
smoothTouch	number \| false	0.1	Touch device smoothing (false = native)
normalizeScroll	boolean	true	Normalize scroll behavior across browsers
respectReducedMotion	boolean	true	Honor OS reduced motion setting
onCreated	function	-	Callback when ScrollSmoother is ready

Advanced Usage

Custom Configuration

import { CrystalScrollSmoother } from '@artasce/crystal-ui';

<CrystalScrollSmoother
  smooth={2}              // Extra smooth
  effects={true}          // Enable parallax
  desktopOnly={true}      // Native scroll on mobile
  breakpoint={1024}       // Larger breakpoint
  smoothTouch={false}     // No touch smoothing
  normalizeScroll={true}  // Consistent behavior
  onCreated={(smoother) => {
    // Access ScrollSmoother instance
    console.log('ScrollSmoother ready!', smoother);

    // Scroll to element
    smoother.scrollTo('#section-2', true, 'center center');
  }}
>
  {children}
</CrystalScrollSmoother>

Important Notes

Fixed elements outside: Headers, FABs, and other fixed-position elements must be placed outside the CrystalScrollSmoother wrapper to maintain their fixed positioning.

CSS required: Import the crystal-ui styles in your app to get the required wrapper CSS. If using crystal-ui globals, this is automatic.

Single instance: Only one CrystalScrollSmoother should be active at a time. Typically placed in your root layout.

Live Demo

Experience ScrollSmoother with parallax effects in a full-page demo.

Open Full-Page Demo