useScrollProgress

Relevant source files

The following files were used as context for generating this wiki page:

• src/hooks/useScrollProgress.ts
• src/hooks/index.ts
• src/index.ts
• package.json
• src/transitions/inertia.ts

The useScrollProgress module is a core part of the @pcstyle/motion library's hooks collection. It provides a specialized set of React hooks designed to track and transform scroll-based data into MotionValue objects, facilitating reactive animations based on user scroll behavior. These hooks wrap the underlying framer-motion scroll utilities to offer a simplified API for tracking element-specific scroll progress, global scroll positions, and mapping scroll values to custom output ranges.

Sources: src/hooks/useScrollProgress.ts:1-49, package.json:1-15, src/hooks/index.ts:1-5

Core Architecture and Data Flow

The module leverages framer-motion's useScroll and useTransform hooks to handle complex scroll calculations. It acts as a wrapper that abstracts the configuration of scroll offsets and range mapping.

Data Flow Diagram

The following diagram illustrates how scroll data flows from the DOM through the useScrollProgress hooks to become reactive animation values.

Hook Definitions

The module exports three primary hooks to handle different scroll tracking scenarios.

useScrollProgress

This hook tracks the scroll progress of a specific element relative to the viewport. It returns a MotionValue<number> that fluctuates between 0 and 1.

• Logic: It utilizes a default offset of ["start end", "end start"] if no options are provided, meaning the animation starts when the top of the element hits the bottom of the viewport and ends when the bottom of the element leaves the top of the viewport.
• Parameters:
  • ref: A RefObject pointing to the HTML element to track.
  • options: Optional configuration for scroll offsets.

Sources: src/hooks/useScrollProgress.ts:18-30

useScrollTransform

This utility hook extends useScrollProgress by mapping the 0-1 progress value to a specific range of output values (e.g., colors, pixel values, or strings).

• Logic: It automatically generates an inputRange based on the length of the provided outputRange. For example, an output range of [0, 100, 200] would automatically create an input range of [0, 0.5, 1].
• Parameters:
  • ref: Ref to the target element.
  • outputRange: An array of values the scroll progress should map to.
  • options: Optional scroll progress configuration.

Sources: src/hooks/useScrollProgress.ts:35-42

useScrollPosition

A simplified hook for tracking global window scroll positions.

• Returns: An object containing scrollY (absolute pixel value) and scrollYProgress (global percentage from 0-1).

Sources: src/hooks/useScrollProgress.ts:47-50

Configuration and Types

The module defines specific types to ensure strict scroll offset configuration.

Scroll Progress Options

The ScrollProgressOptions interface allows developers to define when an element's scroll progress should begin and end.

Property	Type	Description
offset	ScrollOffsetValue[]	Defines the intersection points between target and container.

Sources: src/hooks/useScrollProgress.ts:6-12

Edge Definitions

The Edge and ScrollOffsetValue types define valid string literal combinations for offsets.

type Edge = "start" | "end" | "center";
type ScrollOffsetValue = Edge | `${Edge} ${Edge}`;

Sources: src/hooks/useScrollProgress.ts:6-7

Integration with Library Ecosystem

useScrollProgress is exported as part of the primary @pcstyle/motion/hooks entry point. It is intended to work alongside other motion utilities like inertia transitions for smooth scroll-related behaviors.

Integration Point	File Path	Usage
Public API	src/index.ts	Exported as part of the main package.
Hook Registry	src/hooks/index.ts	Organized alongside sequence and accessibility hooks.
Inertia Transitions	src/transitions/inertia.ts	Provides presets like inertiaScroll for decelerating motion.

Sources: src/index.ts:11-18, src/hooks/index.ts:1-5, src/transitions/inertia.ts:7-13

Summary

The useScrollProgress module provides a specialized set of tools for creating scroll-driven interactions. By abstracting framer-motion's core utilities into element-specific and global tracking hooks, it allows for the creation of reactive interfaces that respond precisely to the user's position in the document. Its tight integration with TypeScript ensures that scroll offsets and transformations remain type-safe.

Sources: src/hooks/useScrollProgress.ts:1-50, package.json:1-10