useScrollIntoView

React sensor hook works like element.scrollIntoView()

useScrollIntoView provides a smooth, animated scroll to a target element, similar to Element.scrollIntoView() but with more control. It returns an object with scrollIntoView (accepting alignment options like "start", "end", "center") and cancel functions. You can configure the scroll axis, duration, easing function, offset, and whether the user can interrupt the animation by scrolling.

When to Use

• Scrolling to anchored sections with smooth, customizable animation (e.g., table of contents navigation)
• Focusing on newly added content, error messages, or form fields after validation
• Building scrollable lists where selecting an item scrolls it into the visible area

Notes

• SSR-safe: Returns no-op functions during server-side rendering. No DOM scrolling occurs on the server.
• Cancelable: Set cancelable: true (default) to allow the user to interrupt the scroll animation by manually scrolling. Set isList: true to prevent content jumping in lists.
• Related hooks: See also useScroll for tracking scroll position and state, and useScrollLock for preventing scroll entirely.

Usage

function Demo() {
  const targetRef = useRef<HTMLParagraphElement>(null);
  const { scrollIntoView } = useScrollIntoView(targetRef, {
    offset: 60,
  });

  return (
    <div>
      <button onClick={() => scrollIntoView({ alignment: "center" })}>
        Scroll to target
      </button>
      <div style={{ height: "50vh" }} />
      <p ref={targetRef}>Hello there</p>
    </div>
  );
};

API

useScrollIntoView

Returns

{ scrollIntoView: (animation?: UseScrollIntoViewAnimation | undefined) => void; cancel: () => void; }: A object with the following elements:

• scrollIntoView: scroll target element into viewport
• cancel: cancel scroll function

Arguments

UseScrollIntoViewAnimation

UseScrollIntoViewParams

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;