The last script for animated scrolling you ever need.
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:
Name | Type | Default | Description |
---|---|---|---|
target* | number|number[]]|HTMLElement|string |
— | A number (y-value), an array of two numbers (x and y values), HTML element or the element selector. |
options | object |
{} |
Custom options, extends the initial options for current invocation. |
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:
Name | Type | Default | Description |
---|---|---|---|
axis* | string |
— | Whether to add the elements to the x or y category of fixedElements option. |
alignment* | string |
— | Whether to add the elements to the start or end category of fixedElements option. |
elements* | ...(HTMLElement|string) |
— | The elements being added. |
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:
Name | Type | Default | Description |
---|---|---|---|
elements* | ...(HTMLElement|string) |
— | The elements being removed. |
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();
});