Welcome to Mantine, React components library that you always wished for
Welcome to Mantine, React components library that you always wished for

use-scroll-into-view

Scrolls given element into view

Import

Source

View source code

Docs

Edit this page

Package

@mantine/hooks

Usage

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.

Hello there

import { useScrollIntoView } from '@mantine/hooks';
import { Button, Text, Group, Box } from '@mantine/core';

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

  return (
    <Group justify="center">
      <Button
        onClick={() =>
          scrollIntoView({
            alignment: 'center',
          })
        }
      >
        Scroll to target
      </Button>
      <Box
        style={{
          width: '100%',
          height: '50vh',
          backgroundColor: 'var(--mantine-color-blue-light)',
        }}
      />
      <Text ref={targetRef}>Hello there</Text>
    </Group>
  );
}

API

The hook is configured with settings object:

  • onScrollFinish – function that will be called after scroll animation
  • easing – custom math easing function
  • duration - duration of scroll animation in milliseconds
  • axis - axis of scroll
  • cancelable - indicator if animation may be interrupted by user scrolling
  • offset - additional distance between the nearest edge and element
  • isList - 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 animation
  • cancel – function that stops scroll animation
  • targetRef - ref of target HTML node
  • scrollableRef - 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' });

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 me into view

import { useScrollIntoView } from '@mantine/hooks';
import { Button, Text, Group, Paper, Box } from '@mantine/core';

function Demo() {
  const { scrollIntoView, targetRef, scrollableRef } = useScrollIntoView<
    HTMLDivElement,
    HTMLDivElement
  >();

  return (
    <Group justify="center">
      <Paper ref={scrollableRef} h={300} style={{ overflowY: 'scroll', flex: 1 }}>
        <Box pt={260} pb={450}>
          <Paper
            ref={targetRef}
            p="xl"
            style={{
              backgroundColor: 'var(--mantine-color-blue-light)',
              width: '100%',
            }}
          >
            <Text>Scroll me into view</Text>
          </Paper>
        </Box>
      </Paper>
      <Button onClick={() => scrollIntoView()}>Scroll to target</Button>
    </Group>
  );
}

Scroll X axis

Scroll me into view

import { useScrollIntoView } from '@mantine/hooks';
import { Button, Text, Group, Paper, Box } from '@mantine/core';

function Demo() {
  const { scrollIntoView, targetRef, scrollableRef } = useScrollIntoView<
    HTMLDivElement,
    HTMLDivElement
  >({ axis: 'x' });

  return (
    <Group justify="center">
      <Paper ref={scrollableRef} h={150} w={300} style={{ overflowX: 'scroll' }}>
        <Box pl={260} pr={450}>
          <Paper
            ref={targetRef}
            p="md"
            style={{
              backgroundColor: 'var(--mantine-color-blue-light)',
              width: 'max-content',
            }}
          >
            <Text>Scroll me into view</Text>
          </Paper>
        </Box>
      </Paper>
      <Button onClick={() => scrollIntoView()}>Scroll to target</Button>
    </Group>
  );
}

Definition

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

Previous

use-resize-observer

Next

use-viewport-size

Welcome to Mantine, React components library that you always wished for

Build fully functional accessible web applications faster than ever

About

ContributeAbout MantineChangelogGitHub Releases

Community

Chat on DiscordFollow on XFollow on GithubGitHub discussions

Project

Mantine UIHelp CenterGithub organizationnpm organization

Built by Vitaly Rtishchev and these awesome people