useScroll

Hook that allows you to control scroll a element

sensors

low

test coverage

Last changed: 5 days ago

Installation

Library

CLI

Manual

import { useScroll } from '@siberiacancode/reactuse';

Usage

const { scrolling, scrollIntoView, scrollTo} = useScroll(ref, options);
// or
const { scrolling, scrollIntoView, scrollTo} = useScroll(ref, () => console.log('callback'));
// or
const { ref, scrolling, scrollIntoView, scrollTo} = useScroll(options);
// or
const { ref, scrolling, scrollIntoView, scrollTo} = useScroll(() => console.log('callback'));

Demo

source

Api

Parameters

Name	Type	Default	Note
options.behavior?	ScrollBehavior	auto	The behavior of scrolling
options.offset.left?	number	0	The left offset for arrived states
options.offset.right?	number	0	The right offset for arrived states
options.offset.top?	number	0	The top offset for arrived states
options.offset.bottom?	number	0	The bottom offset for arrived states
options.onScroll?	(params: UseScrollCallbackParams, event: Event) => void	-	The callback function to be invoked on scroll
options.onStop?	(event: Event) => void	-	The callback function to be invoked on scroll end

Returns

UseScrollReturn

Parameters

Name	Type	Default	Note
callback?	(params: UseScrollCallbackParams, event: Event) => void	-	The callback function to be invoked on scroll

Returns

UseScrollReturn

Parameters

Name	Type	Default	Note
target?	Target	window	The target element to scroll
options.behavior?	ScrollBehavior	auto	The behavior of scrolling
options.offset.left?	number	0	The left offset for arrived states
options.offset.right?	number	0	The right offset for arrived states
options.offset.top?	number	0	The top offset for arrived states
options.offset.bottom?	number	0	The bottom offset for arrived states
options.onScroll?	(params: UseScrollCallbackParams, event: Event) => void	-	The callback function to be invoked on scroll
options.onStop?	(event: Event) => void	-	The callback function to be invoked on scroll end

Returns

UseScrollReturn & { ref: StateRef<Target> }

Parameters

Name	Type	Default	Note
target	Target	-	The target element to scroll
callback?	(params: UseScrollCallbackParams, event: Event) => void	-	The callback function to be invoked on scroll

Returns

UseScrollReturn & { ref: StateRef<Target> }

Type declaration

import type { HookTarget } from '@/utils/helpers';

import type { StateRef } from '../useRefState/useRefState';

export interface UseScrollOptions {
  /** The on scroll callback */
  onScroll?: (params: UseScrollCallbackParams, event: Event) => void;

  /** The on end scroll callback */
  onStop?: (event: Event) => void;

  /** Offset arrived states by x pixels. */
  offset?: {
    left?: number;
    right?: number;
    top?: number;
    bottom?: number;
  };
}

export interface UseScrollCallbackParams {
  /** The element x position */
  x: number;
  /** The element y position */
  y: number;
  /** State of scroll arrived */
  arrived: {
    left: boolean;
    right: boolean;
    top: boolean;
    bottom: boolean;
  };
  /** State of scroll direction */
  directions: {
    left: boolean;
    right: boolean;
    top: boolean;
    bottom: boolean;
  };
}

export interface ScrollIntoViewParams {
  behavior?: ScrollBehavior;
  block?: ScrollLogicalPosition;
  inline?: ScrollLogicalPosition;
}

export interface ScrollToParams {
  behavior?: ScrollBehavior;
  x: number;
  y: number;
}

export interface UseScrollReturn {
  /** The state of scrolling */
  scrolling: boolean;
  /** Function to scroll element into view */
  scrollIntoView: (params?: ScrollIntoViewParams) => void;
  /** Function to scroll element to a specific position */
  scrollTo: (params?: ScrollToParams) => void;
}

export interface UseScroll {
  (
    target?: HookTarget,
    callback?: (params: UseScrollCallbackParams, event: Event) => void
  ): UseScrollReturn;

  (target?: HookTarget, options?: UseScrollOptions): UseScrollReturn;

  <Target extends Element>(
    callback?: (params: UseScrollCallbackParams, event: Event) => void,
    target?: never
  ): UseScrollReturn & { ref: StateRef<Target> };

  <Target extends Element>(
    options?: UseScrollOptions,
    target?: never
  ): UseScrollReturn & {
    ref: StateRef<Target>;
  };
}

Source

Source • Demo

Contributors

D

debabin

E

Evgen41kk