Use Scroll Into View

import { UseScrollIntoViewDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.useScrollIntoView);

Usage

The use-scroll-into-view hook handles scroll behavior for any scrollable element. Basic usage works the same way as element.scrollIntoView(). The hook adjusts the scrolling animation with respect to the reduced-motion user preference.

API

The hook is configured with a settings object:

• onScrollFinish – function that will be called after the scroll animation
• onScrollCancel – function that will be called when the scroll animation is canceled by user interaction
• easing – custom math easing function
• duration - duration of the scroll animation in milliseconds
• axis - axis of the scroll
• cancelable - indicator if the animation may be interrupted by user scrolling
• offset - additional distance between the nearest edge and the element
• isList - indicator that prevents content jumping in scrolling lists with multiple targets, for example Select, Carousel

The hook returns an object with:

• scrollIntoView – function that starts the scroll animation
• cancel – function that stops the scroll animation
• scrolling – boolean indicating whether a scroll animation is in progress
• targetRef - ref of the target HTML node
• scrollableRef - ref of the scrollable parent HTML element; if not used, the document element will be used

The returned scrollIntoView function accepts a single optional argument alignment - optional target element alignment relative to the parent based on the current axis.

import { useScrollIntoView } from '@mantine/hooks';

const { scrollIntoView } = useScrollIntoView();

scrollIntoView({ alignment: 'center' });

Easing

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
});

Parent node

Scroll X axis

Definition

interface UseScrollIntoViewAnimation {
  /** Target element alignment relatively to parent based on current axis */
  alignment?: 'start' | 'end' | 'center';
}

interface UseScrollIntoViewOptions {
  /** Callback fired after scroll */
  onScrollFinish?: () => void;

  /** Callback fired when scroll animation is canceled by user interaction */
  onScrollCancel?: () => 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;
}

export interface UseScrollIntoViewReturnValue<
  Target extends HTMLElement = any,
  Parent extends HTMLElement | null = null,
> {
  scrollableRef: React.RefObject<Parent | null>;
  targetRef: React.RefObject<Target | null>;
  scrollIntoView: (params?: UseScrollIntoViewAnimation) => void;
  cancel: () => void;
  scrolling: boolean;
}

function useScrollIntoView<
  Target extends HTMLElement = any,
  Parent extends HTMLElement | null = null
>(
  options?: UseScrollIntoViewOptions,
): UseScrollIntoViewReturnValue<Target, Parent>

Exported types

UseScrollIntoViewOptions and UseScrollIntoViewReturnValue types are exported from the @mantine/hooks package; you can import them in your application:

import type { UseScrollIntoViewOptions, UseScrollIntoViewReturnValue } from '@mantine/hooks';