scrolls.js - smooth scrolling library

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">&#x25b2;</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.