import { HooksDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';
export default Layout(MDX_DATA.useScrollIntoView);
use-scroll-into-view
handles scroll behavior for any scrollable element. Basic usage works the same way as element.scrollIntoView()
.
Hook adjusts scrolling animation with respect to the reduced-motion
user preference.
The hook is configured with settings object:
onScrollFinish
– function that will be called after scroll animationeasing
– custom math easing functionduration
- duration of scroll animation in millisecondsaxis
- axis of scrollcancelable
- indicator if animation may be interrupted by user scrollingoffset
- additional distance between the nearest edge and elementisList
- indicator that prevents content jumping in scrolling lists with multiple targets, for example Select, Carousel
Hook returns an object with:
scrollIntoView
– function that starts scroll animationcancel
– function that stops scroll animationtargetRef
- ref of target HTML nodescrollableRef
- ref of scrollable parent HTML element, if not used document element will be used
Returned scrollIntoView
function accepts single optional argument alignment
- optional target element alignment relatively to parent based on current axis.
import { useScrollIntoView } from '@mantine/hooks';
const { scrollIntoView } = useScrollIntoView();
scrollIntoView({ alignment: 'center' });
The hook accept custom easing
math function to control the flow of animation.
It takes t
argument, which is a number between 0
and 1
.
Default easing is easeInOutQuad
- more info here.
You can find other popular examples on easings.net
import { useScrollIntoView } from '@mantine/hooks';
useScrollIntoView({
easing: (t) => (t < 0.5 ? 16 * t ** 5 : 1 - (-2 * t + 2) ** 5 / 2), // easeInOutQuint
});
interface ScrollIntoViewAnimation {
/** target element alignment relatively to parent based on current axis */
alignment?: 'start' | 'end' | 'center';
}
interface ScrollIntoViewParams {
/** callback fired after scroll */
onScrollFinish?: () => void;
/** duration of scroll in milliseconds */
duration?: number;
/** axis of scroll */
axis?: 'x' | 'y';
/** custom mathematical easing function */
easing?: (t: number) => number;
/** additional distance between nearest edge and element */
offset?: number;
/** indicator if animation may be interrupted by user scrolling */
cancelable?: boolean;
/** prevents content jumping in scrolling lists with multiple targets */
isList?: boolean;
}
interface ScrollIntoViewReturnType<
Target extends HTMLElement,
Parent extends HTMLElement | null = null,
> {
scrollableRef: React.MutableRefObject<Parent>;
targetRef: React.MutableRefObject<Target>;
scrollIntoView: (params?: ScrollIntoViewAnimation) => void;
cancel: () => void;
}
function useScrollIntoView<
Target extends HTMLElement,
Parent extends HTMLElement | null = null,
>({
duration,
axis,
onScrollFinish,
easing,
offset,
cancelable,
isList,
}?: ScrollIntoViewParams): ScrollIntoViewReturnType<Target, Parent>;