useScroll

Hook that allows you to control scroll a element

sensors

low

test coverage

Last changed: 16 minutes 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 {
  /** Offset arrived states by x pixels. */
  offset?: {
    left?: number;
    right?: number;
    top?: number;
    bottom?: number;
  };

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

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

export interface UseScrollCallbackParams {
  /** 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;
  };
  /** The element x position */
  x: number;
  /** The element y position */
  y: number;
}

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

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

export interface UseScrollReturn {
  /** The latest scroll value snapshot */
  snapshot: UseScrollCallbackParams;
  /** Function to scroll element into view */
  scrollIntoView: (params?: ScrollIntoViewParams) => void;
  /** Function to scroll element to a specific position */
  scrollTo: (params?: ScrollToParams) => void;
  /** Function to enable subscriptions and rerender on next updates */
  watch: () => UseScrollCallbackParams;
}

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