@clvarley/simple-scroll
v1.1.0
Published
Simple utility to make scrolling elements into view easier.
Downloads
6
Readme
@clvarley/simple-scroll
The small utility that aims to make scrolling to elements simple.
About
Getting the browser to scroll to a given element can be a pain. While APIs like
Element.scrollIntoView
and window.scroll
can get us there, they can be fiddly to use and don't offer us much in the way
of customisation.
Simple scroll is a small utility that offers a no-frills, no-nonesense way of easily scrolling elements into view.
Installation
Firstly, make sure to download the library like so:
npm install --save @clvarley/simple-scroll
After npm has installed the library, it can be imported into your projects as normal:
ES6 module*preferred
import {simpleScroll} from '@clvarley/simple-scroll';
CommonJS
const {simpleScroll} = require('@clvarley/simple-scroll');
Getting Started
Now that you have the library installed and imported, we can begin to use it. Simple scroll offers a very simple API, in it's most basic form it can be used as follows:
import {simpleScroll} from '@clvarley/simple-scroll';
const someElement = document.querySelector('#some-element-id');
simpleScroll(someElement);
Just pass the element you want to view and simpleScroll
will scroll the window
there!
When this code gets run - for example inside an event listener - the window will
be softly scrolled to the #some-element-id
. If that's all you need, you can
stop reading here and get building!
Options
However, it's likely you will want to modify the default behavior of
simpleScroll
to better suit your needs. The behaviour of simpleScroll
can be
customised by passing an options object through via the (optional) second
parameter.
import {simpleScroll} from '@clvarley/simple-scroll';
const someElement = document.querySelector('#some-element-id');
simpleScroll(someElement, {
duration: 2500,
padding: 32
});
Here we've modified the default scroll behaviour. Now, the scroll will happen over the course of 2500 milliseconds (2.5s) and will leave 32px of padding above the element. (To accommodate for a fixed navbar, for example)
At the current time there are only 3 properties that can be set, but we hope to expose more in the future.
| Property | Type | Purpose | Default |
| :------- | :--- | :------ | :------ |
| duration
| number
| Time (in milliseconds) the scroll animation should take* | 0 |
| padding
| number
| Padding (in pixels) to be left above the element | 0 |
| focus
| boolean
| Whether or not to focus the element after scroll | false
|
| timing
| function
| Function used to control how the animation will be timed | TIMING_EASE_IN_OUT |
Caveats
As standard simpleScroll
respects the prefers-reduced-motion
setting. On systems where this flag has been enabled the duration
and
timing
options are silently ignored, with control instead being handled by the
default browser scrolling behaviour.
If you find your scroll animations aren't respecting the duration
option this
may be why.
Timing
By default, simpleScroll
uses a cubic ease-in-out
curve for its animation (similar to how properties animate when using the
ease-in-out
value for CSS transitions). This is a good general "all rounder"
and looks adequate in most places, but we also provide a set of other animation
styles should you wish to use them.
Linear
Linear timing, with no acceleration or change in speed over the course of the animation. Scrolls straight to the target and stops.
simpleScroll(someElement, {
timing: simpleScroll.TIMING_LINEAR
});
Ease-in
Timing with a slow start that accelerates. Gets faster over time and comes to a sharp stop at the target element.
simpleScroll(someElement, {
timing: simpleScroll.TIMING_EASE_IN
});
Ease-out
Timing with a fast start that decelerates. Gets slower over time and comes to a gentle stop at the target element.
simpleScroll(someElement, {
timing: simpleScroll.TIMING_EASE_OUT
});
Ease-in-out
The default.
Timing that accelerates at first, then decelerates as it approaches the end. Starts slow, picking up pace until the halfway mark then slowing down and gently stopping at the target element.
simpleScroll(someElement, {
timing: simpleScroll.TIMING_EASE_IN_OUT
});
Custom Timing
Not happy with the defaults provided? You can also specify your own timing!
Passing a function of your own as the timing
option is also allowed. Your
custom callback must take one argument, a decimal number representing the
current time elapsed between 0 and 1 (0 for just started, 0.5 for halfway, 1
for finished and so on) and must return a number within the same bounds (0 to 1)
that represents how far you wish the animation to have progressed.
For those of you familiar with TypeScript the signature should look like this:
function myTimingCallback(elapsed: number): number {
/* your logic here */
};
For inspiration, and for ideas of the sort of thing you might want to try, why not take a look at some of the examples on easings.net.