useScrollIntoView

Hook to scroll an element into view.

Loading demo…

Show source code

import { useScrollIntoView } from "../../../../hooks/events/useScrollIntoView";

export const UseScrollIntoView = () => {
	const { scroll, targetRef } = useScrollIntoView<HTMLParagraphElement, HTMLDivElement>({
		scrollableElement: ()=>document.querySelector('.container') as HTMLDivElement
	});

	return (
		<div>
			<button
				onClick={()=>scroll('start')}
			>
				Scroll to target
			</button>
			<div
				style={{
					width: '100%',
					height: '50vh',
				}}
			/>
			<p ref={targetRef}>Hello there</p>
		</div>
	);
}

Types

UseScrollIntoViewProps

• @template E - The scrollable container element type. Defaults to null, which means the nearest scrollable ancestor is used automatically.

Parameters accepted by useScrollIntoView.

Property	Type	Required	Description
duration	number		Duration of the scroll animation in milliseconds. Defaults to 1000.
axis	"x" \| "y"		The scroll axis to animate along: - "y" (default) — Vertical scrolling. - "x" — Horizontal scrolling.
animation	(t: number) => number		An easing function that maps a normalised time value t ∈ [0, 1] to a progress value, controlling the acceleration curve of the scroll animation. Defaults to easeInOutSine when omitted.
offset	number		Additional scroll offset in pixels applied after the target element is aligned. Positive values scroll past the target; negative values stop short of it. Defaults to 0.
cancelable	boolean		When true, the ongoing scroll animation can be interrupted by user input (e.g. a manual scroll gesture). Defaults to false.
onFinish	() => void		Called when the scroll animation completes successfully (i.e. reaches the target position without being cancelled).
scrollableElement	(() => E) \| E \| RefObject<E \| null>	✓	The scrollable container element to scroll within. Accepts a factory function () =&gt; E, a direct element reference, or a React RefObject&lt;E | null&gt;. When the resolved value is null, the nearest scrollable ancestor of the target element is used automatically.

UseScrollIntoViewResult

• @template T - The element type to scroll into view.

Return value of useScrollIntoView.

Property	Type	Required	Description
targetRef	React.MutableRefObject<T \| null>	✓	A mutable ref to attach to the target element that should be scrolled into view. Must be attached for {@link UseScrollIntoViewResult.scroll} to work.
scroll	(alignment?: "start" \| "center" \| "end") => void	✓	Starts the scroll animation, bringing the target element into view within the scrollable container. Accepts an optional alignment hint: - "start" — Aligns the top (or left) edge of the target with the top (or left) of the container. - "center" (default) — Centers the target within the container. - "end" — Aligns the bottom (or right) edge of the target with the bottom (or right) of the container.
cancel	() => void	✓	Cancels the currently running scroll animation, if any. Only has an effect when cancelable is true in the hook options.