@iampoul/react-parallax

react-parallax.dev · npm · GitHub

A performant, accessible React parallax component with scroll and pointer-based motion.

Installation

npm install @iampoul/react-parallax

Usage

import { Parallax, ParallaxLayer } from "@iampoul/react-parallax"

function App() {
  return (
    <Parallax mode="both" intensity={1} smoothing={0.12}>
      {/* Background layer - moves slower, appears further */}
      <ParallaxLayer speed={0.5} pointerStrength={20}>
        <img src="/background.png" alt="" />
      </ParallaxLayer>

      {/* Foreground layer - moves faster, appears closer */}
      <ParallaxLayer speed={-0.3} pointerStrength={40} zIndex={1}>
        <img src="/foreground.png" alt="" />
      </ParallaxLayer>
    </Parallax>
  )
}

Horizontal parallax

For side-scrolling layouts, pass direction="horizontal" to drive scroll progress from the horizontal axis. Set axis="x" on layers so they translate along the same direction as the scroll.

const wrapperRef = useRef<HTMLDivElement>(null)

<div ref={wrapperRef} style={{ overflowX: "scroll", display: "flex" }}>
  <Parallax
    direction="horizontal"
    mode="scroll"
    scrollParent={wrapperRef.current}
    overflow="visible"
    style={{ width: "300vw", height: "100vh" }}
  >
    <ParallaxLayer speed={0.4} axis="x">
      <img src="/clouds.png" alt="" />
    </ParallaxLayer>
    <ParallaxLayer speed={0.8} axis="x" zIndex={1}>
      <img src="/mountains.png" alt="" />
    </ParallaxLayer>
  </Parallax>
</div>

API

<Parallax>

The container that tracks scroll + pointer motion and broadcasts it to child layers.

| Prop | Type | Default | Description | |------|------|---------|-------------| | mode | "scroll" \| "pointer" \| "both" | "both" | Which inputs drive the parallax effect | | direction | "vertical" \| "horizontal" | "vertical" | Scroll axis that drives progress. Use "horizontal" for side-scrolling layouts — pairs with axis="x" on layers | | intensity | number | 1 | Global movement multiplier (0.5 = subtle, 2 = dramatic) | | smoothing | number | 0.12 | Easing factor (lower = floatier, 1 = instant). Ignored when springConfig is set | | springConfig | { stiffness?: number; damping?: number } | – | Spring physics alternative to lerp — gives natural overshoot. stiffness default 120, damping default 14 | | onProgress | (state: ParallaxState) => void | – | Callback fired every frame with current scroll/pointer state | | disabled | boolean | false | Pause all motion (auto-enabled for reduced-motion) | | scrollParent | HTMLElement \| null | window | Custom scroll container — use when <Parallax> is inside a scrollable div, modal, or sidebar | | overflow | string | "hidden" | CSS overflow on the container — set to "visible" to let layers bleed outside bounds | | as | ElementType | "div" | HTML element to render | | className | string | – | CSS class for the container | | style | CSSProperties | – | Inline styles |

<ParallaxLayer>

A single moving object inside a <Parallax> container.

| Prop | Type | Default | Description | |------|------|---------|-------------| | speed | number | 0.3 | Depth: 0 = locked, >0 = slower/background, <0 = faster/foreground | | pointerStrength | number | 0 | Pixels of travel from pointer movement | | scrollRange | number \| string | 120 | Max scroll travel — absolute px or "25%" of container height | | axis | "x" \| "y" \| "both" | "y" | Axis for scroll parallax | | rotate | number | 0 | Degrees of rotation across scroll range | | scale | number | 0 | Extra scale at scroll edges (0.2 = +20%) | | fade | number | 1 | Opacity at edges (1 = no fade) | | blur | number | 0 | Max blur in px at scroll edges, 0 at center — creates a depth-of-field focus effect | | blurBase | number | 0 | Constant blur in px always applied — use for layers that should always appear out of focus | | zIndex | number | 0 | Stacking order | | as | ElementType | "div" | HTML element to render | | className | string | – | CSS class | | style | CSSProperties | – | Inline styles |

useParallax()

Hook to access the parallax context from custom components.

const { intensity, disabled, mode, subscribe, getState } = useParallax()

Features

• Zero dependencies (only React peer dependency)
• Performant - Single rAF loop, ref-based subscriptions, no React re-renders
• Accessible - Respects prefers-reduced-motion
• Flexible - Scroll, pointer, or both; customize speed, rotation, scale, fade
• TypeScript - Full type definitions included

License

MIT