Basic Info
A smooth scrolling library built to provide convenience for developers.
If you like this project you may like our durations.js animated durations library!
Features
- Plug-and-play (unless you have other JavaScript that uses
scrolls()
already...) - Number or selector-based targeting
- Allows a function to be called when scrolling has ended
- Customizeable duration of movement and offset position from the stop position
- Fully open source
Getting Started
Installation
You can install the libaray via npm:
npm i scrolls.js
or via CDN:
Source Version
<script src="https://cdn.jsdelivr.net/npm/[email protected]/scrolls.js"></script>
Minified Version
<script src="https://cdn.jsdelivr.net/npm/[email protected]/scrolls.min.js"></script>
Usage
scrolls(0); // Scroll to the top of the page.
scrolls('h1', {
durationOfMovement: 5000 // Defaults to 1000, or 1 second.
});
Examples
Back-To-Top
HTML:
<button class="btt js-btt">▲</button>
CSS:
<style>
/**
* Variables for matching this site's color scheme.
*/
html {
--primary-hue: 257;
--primary-saturation: 100%;
--primary-lightness: 77%;
--theme-lightness: 100%;
font-size: 16px;
}
.btt {
background: none;
background-color: hsla(var(--primary-hue), var(--primary-saturation), var(--primary-lightness), 0.75);
border: 0.063rem solid hsl(0, 0%, var(--theme-lightness));
bottom: -1.938rem;
color: hsl(0, 0%, var(--theme-lightness));
cursor: default;
font-family: 'Arial', sans-serif;
font-size: 1rem;
height: 1.875rem;
line-height: 1.25rem;
outline: none;
padding: 0.313rem;
position: fixed;
right: 0.625rem;
text-align: center;
transition: all 0.1s linear;
-webkit-appearance: none !important;
width: 1.875rem;
}
.btt.is--shown {
bottom: 0.625rem;
}
.btt:hover {
background-color: hsla(var(--primary-hue), var(--primary-saturation), calc(var(--primary-lightness) * 1.04), 0.85);
}
.btt:active {
background-color: hsla(var(--primary-hue), var(--primary-saturation), calc(var(--primary-lightness) * 0.96), 0.75);
}
</style>
JS:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/scrolls.min.js"></script>
<script>
/**
* Selects the back-to-top button.
*/
const bttButton = document.querySelector('body > .js-btt');
/**
* Scrolls to the top of the page.
*/
const backToTop = () => {
scrolls(0);
};
/**
* Hides the back-to-top button.
*/
const hideBackToTop = () => {
if (bttButton) {
bttButton.classList.remove('is--shown');
}
};
/**
* Shows the back-to-top button.
*/
const showBackToTop = () => {
if (bttButton) {
bttButton.classList.add('is--shown');
}
};
/**
* Listens for the scroll event to occur and updates the main back-to-top button
* accordingly.
*/
window.addEventListener('scroll', () => {
if (bttButton) {
if (window.pageYOffset >= 20) {
showBackToTop();
} else {
hideBackToTop();
}
}
});
/**
* Code setup to execute immediately including initializing events, and their
* liseners.
*/
(() => {
if (bttButton) {
bttButton.addEventListener('click', () => {
backToTop();
});
if (window.pageYOffset >= 20) {
showBackToTop();
}
}
})();
</script>
Landing Page
Are you building a landing page and want to have smooth scrolling from a navigation bar to the different sections of the page? Just copy-and-paste the code below, tweak it to match your environment, and you should have the section scrolling functionality you should be be able to experience here.
HTML:
<nav class="js-nav">
<a href="#features" title="Features">Features</a>
<a href="#pricing" title="Pricing">Pricing</a>
<a href="#team" title="Team">Team</a>
<a href="#contact" title="Contact">Contact</a>
</nav>
Somewhere further down or up the page...
<h2 class="features">Features</h2>
<!-- Features content -->
<h2 class="pricing">Pricing</h2>
<!-- Pricing content -->
<h2 class="team">Team</h2>
<!-- Team content -->
<h2 class="contact">Contact</h2>
<!-- Contact content -->
CSS:
<style>
nav {
text-align: center;
}
nav a {
margin: 0.625rem;
word-break: keep-all;
}
</style>
JS:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/scrolls.min.js"></script>
<script>
const links = document.querySelectorAll('.js-nav a');
/**
* Code setup to execute immediately including initializing events, and their
* liseners.
*/
(() => {
if (links) {
links.forEach((link) => {
const section = link.getAttribute('href').replace('#', '');
link.addEventListener('click', (e) => {
e.preventDefault();
scrolls('.' + section);
});
});
}
})();
</script>
That's it! If you copied the HTML and CSS from the Back-To-Top example from above you should have that functionality as well. Unless you have other code that would interfere with the selectors/styling you should be able to just plug-and-play with these examples!!
Documentation
// Default customizeable variables via an object within the second parameter
// of the function.
let callback; // Function to execute after scrolling has ended
let durationOfMovement = 1000; // Duration of the scrolling
let offsetPosition = 0; // Distance to offset from the stop position
// Pass in an object as the second parameter to customize the behavior.
scrolls('h1', {
callback: () => {
console.log('Scrolling has finished.');
}
});
// The first parameter could be a number or string and is used as the target of
// the scrolling event, for example 0 would be the top of the page, or h1 to
// scroll to the first h1 element.
Changelog
Please see CHANGELOG.md for details.
License
MIT
Copyright © 2018 Purplest, Inc.