sweet-scroll

sweet-scroll.js

ECMAScript2015 Friendly, dependency-free smooth scroll library.

See Demo

FEATURES

• Dependecy-free!!
• ECMAScript2015 friendly
• Use requestAnimationFrame API (IE9 works in setTimeout instead)
• Supports vertical and horizontal scroll
• Supports dynamic trigger (event delegation)
• Supports container for the scroll
• Supports many easing types

USAGE

1. Install

via NPM

$ npm install sweet-scroll

use

import SweetScroll from "sweet-scroll"

via MANUAL

1. Download the sweet-scroll.min.js
2. Load it in the script tag.

<script src="sweet-scroll.min.js"></script>

2. Setup of HTML

<a href="#intro" data-scroll>Go to Introduction</a>
...
<div id="intro">Introduction</div>

3. Initialize SweetScroll

const sweetScroll = new SweetScroll({/* some options */});

OPTIONS

The following options are applied by default. It can be customized as needed.

{
  trigger: "[data-scroll]",       // Selector for trigger (must be a valid css selector)
  header: "[data-scroll-header]", // Selector for fixed header (must be a valid css selector)
  duration: 1000,                 // Specifies animation duration in integer
  delay: 0,                       // Specifies timer for delaying the execution of the scroll in milliseconds
  easing: "easeOutQuint",         // Specifies the pattern of easing
  offset: 0,                      // Specifies the value to offset the scroll position in pixels
  verticalScroll: true,           // Enable the vertical scroll
  horizontalScroll: false,        // Enable the horizontal scroll
  stopScroll: true,               // When fired wheel or touchstart events to stop scrolling
  updateURL: false,               // Update the URL hash on after scroll

  // Callbacks
  initialized: null,
  beforeScroll: null,
  afterScroll: null,
  cancelScroll: null,
  completeScroll: null
}

Easings

Supports the following easing.

• Normal
  • linear
• Quad
  • easeInQuad
  • easeOutQuad
  • easeInOutQuad
• Cubic
  • easeInCubic
  • easeOutCubic
  • easeInOutCubic
• Quart
  • easeInQuart
  • easeOutQuart
  • easeInOutQuart
• Quint
  • easeInQuint
  • easeOutQuint (default)
  • easeInOutQuint
• Sine
  • easeInSine
  • easeOutSine
  • easeInOutSine
• Expo
  • easeInExpo
  • easeOutExpo
  • easeInOutExpo
• Circ
  • easeInCirc
  • easeOutCirc
  • easeInOutCirc
• Elastic
  • easeInElastic
  • easeOutElastic
  • easeInOutElastic
• Back
  • easeInBack
  • easeOutBack
  • easeInOutBack
• Bounce
  • easeInBounce
  • easeOutBounce
  • easeInOutBounce

Live demo

Customizing Tips

Specifies the container

In the following example we have specified in the container for scrolling the #container.

<div id="container">
  <a href="#heading2" data-scroll>Go to Heading2</a>
  ...
  <h2 id="heading2">Heading2</h2>
</div>

// Specified in the CSS Selector
const sweetScroll = new SweetScroll({/* some options */}, "#container");

// Specified in the Element
const sweetScroll = new SweetScroll({/* some options */}, document.getElementById("container"));

Specifies a fixed header

Add the data-scroll-header attribute in order to offset the height of the fixed header.

<header data-scroll-header></header>

Specify the CSS Selector in header option instead of the data-scroll-header attribute.

const sweetScroll = new SweetScroll({
  header: "#header"
});

Override of options for each element

You can override the default options by passing the option in JSON format to the data-scroll-options.

<a href="#target" data-scroll data-scroll-options='{"easing": "easeOutBounce"}'>Go to Target</a>

if you want to use in non anchor element

Will use the data-scroll attribute instead of href.

<button type="button" data-scroll="+=500">Scroll under 500px</button>

Scroll animation in a other page

The following, Introduce one of the mounting method.

const sweetScroll = new SweetScroll();
const hash = window.location.hash;
let needsInitialScroll = false;

document.addEventListener("DOMContentLoaded", function() {
  needsInitialScroll = document.getElementById(hash.substr(1)) != null;
  if (needsInitialScroll) {
    window.location.hash = "";
  }
}, false);

window.addEventListener("load", function() {
  if (needsInitialScroll) {
    sweetScroll.to(hash, {updateURL: true});
  }
}, false);

Live demo

You can also achieve the same thing in other ways by using the provided API.

API

• new SweetScroll(options = {}, container = "body, html")
• to(distance, options = {})
• toTop(distance, options = {})
• toLeft(distance, options = {})
• toElement($el, options = {})
• update(options = {})
• stop(gotoEnd = false)
• destroy()
• Callbacks
  • initialized: function(){}
  • beforeScroll: function(toScroll, trigger){}
  • cancelScroll: function(){}
  • afterScroll: function(toScroll, trigger){}
  • completeScroll: function(isCancel){}

distance to can specify the CSS Selector or scroll position.

Example:

const SweetScroll = new SweetScroll();

// CSS Selector of target element
sweetScroll.to("#footer");

// Object
sweetScroll.to({top: 1000, left: 20});

// Array (top:0, left:1000)
sweetScroll.to([0, 1000]);

// Number (Priority to vertical scroll position. by default.)
sweetScroll.to(500);

// String (Like object syntax)
sweetScroll.to("top: 500, left: 100");

// String (Relative position)
sweetScroll.to("+=500");
sweetScroll.to("-=200");

new SweetScroll(options = {}, container = "body, html")

options: {Object}
container: {String | Element}

Will generate a SweetScroll instance.

Example:

const sweetScroll = new SweetScroll({
  duration: 1200,
  easing: "easeOutBounce"
}, "#container");

to(distance, options = {})

distance: {String | Array | Object}
options: {Object}

Scroll animation to the specified distance.

Example:

sweetScroll.to({top: 1500, left: 400});

toTop(distance, options = {})

distance: {String | Array | Object}
options: {Object}

Vertical scroll animation to the specified distance.

Example:

sweetScroll.toTop(0);

toLeft(distance, options = {})

distance: {String | Array | Object}
options: {Object}

Horizontal scroll animation to the specified distance.

Example:

sweetScroll.toLeft(1500);

toElement($el, options = {})

$el: {Element}
options: {Object}

Scroll animation to the specified Element.

Example:

sweetScroll.toElement(document.getElementById("content"));

update(options = {})

options: {Object}

Will update the SweetScroll instance.
Primarily used in the case of option update.

Example:

sweetScroll.update({
  trigger: "a[href^='#']"
  duration: 3000
});

stop(gotoEnd = true)

gotoEnd: {boolean}

Will stop the current scroll animation.

Example:

sweetScroll.stop(true);

destroy()

Will destroy the SweetScroll instance.
Disable of the method and event handler.

Example:

sweetScroll.destory();

Callbacks

In beforeScroll and afterScroll, you will pass the coordinates and the triggering element in the argument.
In addition, you can stop the scrolling by return a beforeScroll in false.

Example:

const sweetScroll = new SweetScroll({

  // Initialized the instance.
  initialized() {
    console.log("Initialized");
  },

  // Stop scrolling case of trigger element that contains the `is-disabled` class.
  beforeScroll(toScroll, trigger) {
    console.log("Before!!");
    if (trigger && trigger.classList.contains("is-disabled")) {
      return false;
    }
  },

  // If the `wheel` or `touchstart` event is called
  cancelScroll() {
    console.log("Cancel!!");
  },

  // Scroll animation is complete
  afterScroll(toScroll, trigger) {
    console.log("After!!");
  },

  // Scroll animation is complete (`after` or `cancel`)
  completeScroll(isCancel) {
    console.log("Complete!!", isCancel);
  }
});

Extends Class:

The following is a pattern to override a method in the inheritance destination class.

class MyScroll extends SweetScroll {
  initialized() {
    console.log("Initialized");
  }

  beforeScroll(toScroll, trigger) {
    // Stop scrolling case of trigger element that contains the `is-disabled` class.
    if (trigger.classList.contains("is-disabled")) {
      return false;
    }
  }

  cancelScroll() {
    console.log("Canell!!");
  }

  afterScroll(toScroll, trigger) {
    console.log("After!!");
  }

  completeScroll(isCancel) {
    console.log("Complete!!", isCancel);
  }
}

BROWSER SUPPORT

Works in IE9+, and all modern browsers.

LICENCE

Released under the MIT Licence

AUTHOR

tsuyoshiwada

DEVELOPMENT

Initialization of the project.

$ cd /your/project/dir
$ git clone https://github.com/tsuyoshiwada/sweet-scroll.git

Install some dependencies.

$ npm install

Start the development.
You can access to the http://localhost:3000/.

$ npm start

Run lint and testing.

$ npm test

Generates build file.

$ npm run build

---

Bugs, feature requests and comments are more than welcome in the issues

Changelog

0.5.0

• Add completeScroll callback, and method
• Fix comparison of the instance type. HTMLElement -> HTMLElement
• Change before to after update url timing
• Bugfix that occur at the time of URL update of file: protocol.