The last script for animated scrolling you ever need.

• Installation
  • Using yarn
  • Using npm
  • Using yarn
• Usage
  • smooth-scroll
  • smooth-scroll-native
• Options
• API
• Recipes

yarn add @morev/smooth-scroll

npm install @morev/smooth-scroll

pnpm add @morev/smooth-scroll

There are two modules you can use: smooth-scroll and smooth-scroll-native.

Uses the window.requestAnimationFrame.

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll({/* custom options */});
scroll.to('#target-element');

const { SmoothScroll } = require('@morev/smooth-scroll');

const scroll = new SmoothScroll({/* custom options */});
scroll.to('#target-element');

Uses the native scrollTo method with behavior: smooth.

import { SmoothScrollNative } from '@morev/smooth-scroll/native';

const scroll = new SmoothScrollNative({/* custom options */});
scroll.to('#target-element');

const { SmoothScrollNative } = require('@morev/smooth-scroll/native');

const scroll = new SmoothScrollNative({/* custom options */});
scroll.to('#target-element');

import SmoothScroll from '@morev/smooth-scroll/vue';

Vue.use(SmoothScroll, {/* custom options */});

<template>
  <button @click="scrollTo"></button>
</template>

<script>
  export default {
    methods: {
      scrollTo() {
        this.$SmoothScroll.to('#target-element');
      },
    },
  };
</script>

Vue module creates the only instance, so if you need multiple instances, you should use SmoothScroll directly.

{
  element: HTMLElement | Window | 'auto'; // default is 'auto'
}

The element being scrolled, window object, or auto for getting the nearest scrollable ancestor element.

The value auto is suitable in most cases, but sometimes it may cause some unexpected behavior, mostly in scenarios involving fixed elements and/or not unique selectors.
It also does not affects if scroll target is a certain value rather than element.
So it is recommended to set this option explicitly, and maybe to have separated instances to process the page and inner blocks scrolling.

{
  duration: number | [number, number];  // default is `[300, 700]`
}

Scroll animation duration.

This is the number representing the amount of time in milliseconds that it should take to scroll 1000px. The greater the distance, the longer the animation will take (twice as much for 2000px, three times more for 3000px, etc.).

There can also be supplied an array of two values which first value is duration and second value is duration limit. By default, the limit is 2000ms.

Does not affects while using smooth-scroll-native.

{
  // Default value: imported `easeInOutQuad` function
  easing: (time: number, begin: number, change: number, duration: number) => number;
}

The easing function used during the scroll animation.
Can be one of js-easing-functions (included as a dependency).
See the example "Custom animation".

Does not affects while using smooth-scroll-native.

{
  ifNeeded: boolean; // default is `false`
}

Whether to not invoke scrolling if target position is already in viewport.

{
  autofocus: boolean; // default is `false`
}

Whether to set focus to the target element after scrolling.
Affects only if a given target is an element/selector.

It is strongly recommended to set this option to true, at least while navigating through the page.

{
  block: 'start' | 'end' | 'center'; // default is 'start'
}

Alignment of the target element after scrolling by x-axis.
Affects only if a given target is an element/selector.

{
  inline: 'start' | 'end' | 'center'; // default is 'start'
}

Alignment of the target element after scrolling by y-axis.
Affects only if a given target is an element/selector.

{
  offset: number | { x: number; y: number; }; // default is `{ x: 0, y: 0 }`
}

Additional offset(-s) added to the result position values.
Single value treats as Y-axis offset, with object notation can set X and Y offsets both. Affects only if a given target is an element/selector.

Additional offset added to the result x-axis position value.

Additional offset added to the result y-axis position value.

{
  // Empty by default
  fixedElements: {
    x: {
      start: Array<HTMLElement | string>;
      end: Array<HTMLElement | string>;
    };
    y: {
      start: Array<HTMLElement | string>;
      end: Array<HTMLElement | string>;
    };
  };
}

A set of HTML elements (or its selectors) whose sizes should be considered in the result position calculation.
Affects only if a given target is an element/selector.

An array of elements whose sizes should be excluded from the result x-axis position value.

An array of elements whose sizes should be included to the result x-axis position value.

An array of elements whose sizes should be excluded from the result y-axis position value.

An array of elements whose sizes should be included to the result y-axis position value.

Smoothly scrolls to a given target.

Arguments:

Returns:

Promise<number[]> - Promise object representing the array of result x and y scroll position.

Example:

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll();

scroll.to(1000);
scroll.to([0, 1000]);
scroll.to(document.querySelector('#target-element'));
scroll.to('#target-element');
scroll.to('#target-element', {/* override the initial options */});

Dynamically adds fixed elements after initialization.

Arguments:

Returns:

SmoothScroll - The class instance.

Example:

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll();
scroll.addFixedElements('y', 'start', '.element-one', document.querySelector('.element-two'), '.element-three');

Dynamically removes registered fixed elements.

Arguments:

Returns:

SmoothScroll - The class instance.

Example:

import { SmoothScroll } from 'smooth-scroll';

const scroll = new SmoothScroll({
  fixedElements: {
    y: {
      start: [
        document.querySelector('.element-one'),
        'element-two',
      ],
    },
  },
});

scroll.removeFixedElements('.element-one', document.querySelector('.element-two'));

If one element is used in different categories of the fixedElements option, it will be removed everywhere.

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll({
  autofocus: true,
  fixedElements: {
    y: {
      start: ['#sticky-nav.is-fixed'],
    },
  },
});

document.addEventListener('click', (e) => {
  const link = e.target.closest('#sticky-nav .anchor-link');
  if (!link) return;

  scroll.to(link.hash);
  e.preventDefault();
});

import { SmoothScroll } from '@morev/smooth-scroll';
import { easeInQuad } from '@morev/smooth-scroll/easing';

const scroll = new SmoothScroll({
  duration: 600,
  easing: easeInQuad,
});

scroll.to('#target-element');

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll({
  duration: [600, 600], // animation will always take exactly the same amount of time
});

scroll.to('#target-element');

import { SmoothScroll } from '@morev/smooth-scroll';

const isMotionless = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const scroll = new SmoothScroll({
  duration: isMotionless ? 0 : 400,
});

scroll.to('#target-element');

import { SmoothScroll } from '@morev/smooth-scroll';

const scroll = new SmoothScroll();
const target = document.querySelector('#target-element');

scroll.to(target).then(() => {
  const needFocus = target.querySelector('.need-focus');
  needFocus.focus();
});