Readme.md

React Scroll Direction Hook

@smakss/react-scroll-direction is a versatile, lightweight React hook that not only detects the scroll direction but also provides the scroll position in your application with ease. This enhanced functionality includes detecting distances from the top, bottom, left, and right edges of the viewport, making it an ideal solution for advanced scroll-based interactions in your React applications.

Originally inspired by a popular StackOverflow response, this package has evolved into a comprehensive tool for managing scroll detection in React applications.

Demo

Experience the extended capabilities of @smakss/react-scroll-direction on CodeSandbox:

Installation

Install @smakss/react-scroll-direction via npm or yarn:

npm install @smakss/react-scroll-direction
# or
yarn add @smakss/react-scroll-direction

Then, import it into your project:

ES Module:

import useDetectScroll from '@smakss/react-scroll-direction';

For TypeScript projects, import the hook and its types:

import useDetectScroll, {
  Axis,
  Direction
} from '@smakss/react-scroll-direction';

Usage

The useDetectScroll hook takes an options object with the following properties:

• target: The target scrollable element from which to detect scroll direction and position (default: window, must be an HTMLDivElement).
• thr: Threshold for scroll direction change detection (default: 0, accepts only positive values).
• axis: Defines the scroll axis ("y" or "x", default: "y").
• scrollUp: Value returned when scrolling up (y-axis) or left (x-axis) (default: "up" for y-axis, "left" for x-axis).
• scrollDown: Value returned when scrolling down (y-axis) or right (x-axis) (default: "down" for y-axis, "right" for x-axis).
• still: Value returned when there's no scrolling activity (default: "still").

The hook returns an object with two properties:

• scrollDir: Indicates the scroll direction ("up", "down", "left", "right", or "still").
• scrollPosition: An object containing distances from the top, bottom, left, and right edges of the viewport.

Examples

To detect both scroll direction and position:

const { scrollDir, scrollPosition } = useDetectScroll();

// scrollDir: "up", "down", "left", "right", or "still"
// scrollPosition: { top, bottom, left, right }

To customize for horizontal scroll:

const { scrollDir, scrollPosition } = useDetectScroll({ axis: Axis.X });

// scrollDir: "left", "right", or "still"
// scrollPosition: { top, bottom, left, right }

To use a custom scrollable element as a target rather than the default window:

const customElementRef = useRef<HTMLDivElement>(null);
const [customElement, setCustomElement] = useState<HTMLDivElement>();

const scrollDir = useDetectScroll({target: customElement});

useEffect(() => {
    if(customElementRef.current) {
        setHomepageElement(customElementRef.current);
    }
}, [customElementRef])

Contributing

Interested in making contributions to this project? Please see CONTRIBUTING.md for guidelines and details.

Code of Conduct

We value and prioritize the well-being of all our contributors and users. To ensure that this project remains a welcoming space for everyone, please refer to our Code of Conduct.