@immersive-scroll/horizontal-scroll

@immersive-scroll/horizontal-scroll

A high-performance React component for creating horizontal scroll sections pinned to vertical viewport progress.

Installation

pnpm add @immersive-scroll/horizontal-scroll gsap

Usage

import { HorizontalScrollContainer } from '@immersive-scroll/horizontal-scroll';

export function ProductGallery() {
  return (
    <HorizontalScrollContainer scrub={1} pin={true} start="top top">
      <div className="horizontal-track">
        <ProductCard id={1} />
        <ProductCard id={2} />
        <ProductCard id={3} />
      </div>
    </HorizontalScrollContainer>
  );
}

Props

Prop	Type	Default	Description
children	React.ReactNode	Required	The content to be translated horizontally.
className	string	''	CSS class for the pinned container.
trackClassName	string	''	CSS class for the horizontal track.
start	string | number	'top top'	ScrollTrigger start position.
scrub	boolean | number	1	Smoothness of the horizontal translation.
pin	boolean	true	Whether to pin the container during horizontal traversal.

Why use this?

Most horizontal scroll implementations rely on fragile CSS hacks or heavy intersection observer logic. @immersive-scroll/horizontal-scroll uses GSAP and ScrollTrigger under the hood to ensure:

• Pixel-Perfect Sync: Movement is tied directly to the vertical scroll delta.
• Hardware Acceleration: Uses will-change: transform and optimized GPU layers.
• Automatic Resizing: Recalculates metrics on window resize for flawlessly responsive tracks.
• Zero Layout Shifting: The container pins in place, preventing jarring page JUMP.