ECMAScript2015+ & TypeScript Friendly, dependency-free smooth scroll library.

:lollipop: See Demo

Features

• Dependecy-free!!
• ECMAScript2015+ & TypeScript friendly
• Use requestAnimationFrame API
• Supports vertical and horizontal scroll
• Supports dynamic trigger (event delegation)
• Supports container for the scroll
• Supports many easing types
• Supports server-side rendering (Can load without putting out errors.)

Migration Guide

See the Migration Guide

Table of Contents

• Usage
  • 1. Install
  • 2. Setup of HTML
  • 3. Initialize SweetScroll
• Options
• Easings
  • Built-in (22)
  • Advanced (9)
• Customizing Tips
  • Specifying container elements
  • Specify fixed header
  • Override of options for each element
  • If you want to use in non anchor element
  • Do you feel scrolling is slow?
  • Scrolling animation in another page
• API
  • new SweetScroll(options?: PartialOptions, container?: string | Element)
  • SweetScroll.create(options?: PartialOptions, container?: string | Element)
  • to(distance: any, options?: PartialOptions)
  • toTop(distance: any, options?: PartialOptions)
  • toLeft(distance: any, options?: PartialOptions)
  • toElement($el: Element, options?: PartialOptions)
  • update(options: PartialOptions)
  • stop(gotoEnd: boolean = true)
  • destroy()
  • Callbacks
• Browser Support
  • Scrolling with IE9
• CHANGELOG
• Contibute
  • Development
• License

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>

via CDN (UNPKG)

<script src="https://unpkg.com/sweet-scroll/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

You need to initialize an instance after DOMContentLoaded.

document.addEventListener(
  'DOMContentLoaded',
  () => {
    const scroller = new SweetScroll({
      /* some options */
    });
  },
  false,
);

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 or Element for fixed header (Selector of must be a valid css selector)
  duration: 1000,                 // Specifies animation duration in integer
  easing: 'easeOutQuint',         // Specifies the pattern of easing
  offset: 0,                      // Specifies the value to offset the scroll position in pixels
  vertical: true,                 // Enable the vertical scroll
  horizontal: false,              // Enable the horizontal scroll
  cancellable: true,              // When fired wheel or touchstart events to stop scrolling
  updateURL: false,               // Update the URL hash on after scroll (true | false | 'push' | 'replace')
  preventDefault: true,           // Cancels the container element click event
  stopPropagation: true,          // Prevents further propagation of the container element click event in the bubbling phase

  // Callbacks
  before: null,
  after: null,
  cancel: null,
  complete: null,
  step: null,
}

Easings

Supports the following easing.

Built-in (22)

• 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

Advanced (9)

Easing functions that are not built in can pass functions directly.

const scroller = new SweetScroll({
  easing: advancedEasingFunction,
});

Elastic

const easeInElastic = (_, t, b, c, d) => {
  let s = 1.70158;
  let p = 0;
  let a = c;
  if (t === 0) return b;
  if ((t /= d) === 1) return b + c;
  if (!p) p = d * 0.3;
  if (a < Math.abs(c)) {
    a = c;
    s = p / 4;
  } else {
    s = (p / (2 * Math.PI)) * asin(c / a);
  }
  return -(a * Math.pow(2, 10 * (t -= 1)) * Math.sin(((t * d - s) * (2 * Math.PI)) / p)) + b;
};

const easeOutElastic = (_, t, b, c, d) => {
  let s = 1.70158;
  let p = 0;
  let a = c;
  if (t === 0) return b;
  if ((t /= d) === 1) return b + c;
  if (!p) p = d * 0.3;
  if (a < Math.abs(c)) {
    a = c;
    s = p / 4;
  } else {
    s = (p / (2 * Math.PI)) * asin(c / a);
  }
  return a * Math.pow(2, -10 * t) * Math.sin(((t * d - s) * (2 * Math.PI)) / p) + c + b;
};

const easeInOutElastic = (_, t, b, c, d) => {
  let s = 1.70158;
  let p = 0;
  let a = c;
  if (t === 0) return b;
  if ((t /= d / 2) === 2) return b + c;
  if (!p) p = d * (0.3 * 1.5);
  if (a < Math.abs(c)) {
    a = c;
    s = p / 4;
  } else {
    s = (p / (2 * Math.PI)) * Math.asin(c / a);
  }
  if (t < 1) {
    return (
      -0.5 * (a * Math.pow(2, 10 * (t -= 1)) * Math.sin(((t * d - s) * (2 * Math.PI)) / p)) + b
    );
  }
  return (
    a * Math.pow(2, -10 * (t -= 1)) * Math.sin(((t * d - s) * (2 * Math.PI)) / p) * 0.5 + c + b
  );
};

Back

const easeInBack = (_, t, b, c, d, s = 1.70158) => c * (t /= d) * t * ((s + 1) * t - s) + b;

const easeOutBack = (_, t, b, c, d, s = 1.70158) =>
  c * ((t = t / d - 1) * t * ((s + 1) * t + s) + 1) + b;

const easeInOutBack = (_, t, b, c, d, s = 1.70158) =>
  (t /= d / 2) < 1
    ? (c / 2) * (t * t * (((s *= 1.525) + 1) * t - s)) + b
    : (c / 2) * ((t -= 2) * t * (((s *= 1.525) + 1) * t + s) + 2) + b;

Bounce

const easeOutBounce = (_, t, b, c, d) => {
  if ((t /= d) < 1 / 2.75) {
    return c * (7.5625 * t * t) + b;
  } else if (t < 2 / 2.75) {
    return c * (7.5625 * (t -= 1.5 / 2.75) * t + 0.75) + b;
  } else if (t < 2.5 / 2.75) {
    return c * (7.5625 * (t -= 2.25 / 2.75) * t + 0.9375) + b;
  }
  return c * (7.5625 * (t -= 2.625 / 2.75) * t + 0.984375) + b;
};

const easeOutBounce = (_, t, b, c, d) => {
  if ((t /= d) < 1 / 2.75) {
    return c * (7.5625 * t * t) + b;
  } else if (t < 2 / 2.75) {
    return c * (7.5625 * (t -= 1.5 / 2.75) * t + 0.75) + b;
  } else if (t < 2.5 / 2.75) {
    return c * (7.5625 * (t -= 2.25 / 2.75) * t + 0.9375) + b;
  }
  return c * (7.5625 * (t -= 2.625 / 2.75) * t + 0.984375) + b;
};

const easeInBounce = (x, t, b, c, d) => c - easeOutBounce(x, d - t, 0, c, d) + b;

const easeOutBounce = (_, t, b, c, d) => {
  if ((t /= d) < 1 / 2.75) {
    return c * (7.5625 * t * t) + b;
  } else if (t < 2 / 2.75) {
    return c * (7.5625 * (t -= 1.5 / 2.75) * t + 0.75) + b;
  } else if (t < 2.5 / 2.75) {
    return c * (7.5625 * (t -= 2.25 / 2.75) * t + 0.9375) + b;
  }
  return c * (7.5625 * (t -= 2.625 / 2.75) * t + 0.984375) + b;
};

const easeInBounce = (x, t, b, c, d) => c - easeOutBounce(x, d - t, 0, c, d) + b;

const easeInOutBounce = (x, t, b, c, d) =>
  t < d / 2
    ? easeInBounce(x, t * 2, 0, c, d) * 0.5 + b
    : easeOutBounce(x, t * 2 - d, 0, c, d) * 0.5 + c * 0.5 + b;

Live demo

Customizing Tips

Specifying container elements

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 scroller = new SweetScroll(
  {
    /* some options */
  },
  '#container',
);

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

Specify 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 scroller = 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": "easeOutExpo"}'>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>

Scrolling animation in another page

The following, Introduce one of the mounting method.

document.addEventListener(
  'DOMContentLoaded',
  () => {
    const scroller = new SweetScroll();
    const hash = window.location.hash;
    const needsInitialScroll = document.getElementById(hash.substr(1)) != null;

    if (needsInitialScroll) {
      window.location.hash = '';
    }

    window.addEventListener(
      'load',
      () => {
        if (needsInitialScroll) {
          scroller.to(hash, { updateURL: 'replace' });
        }
      },
      false,
    );
  },
  false,
);

Live demo

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

API

new SweetScroll(options?: PartialOptions, container?: string | Element | Window)

Will generate a SweetScroll instance.

Example:

const scroller = new SweetScroll(
  {
    duration: 1200,
    easing: 'easeOutExpo',
  },
  '#container',
);

SweetScroll.create(options?: PartialOptions, container?: string | Element | Window)

Will generate a SweetScroll instance. (factory method)

Example:

const scroller = SweetScroll.create(
  {
    duration: 1200,
    easing: 'easeOutExpo',
  },
  '#container',
);

to(distance: any, options?: PartialOptions)

Scroll animation to the specified distance. distance to can specify the CSS Selector or scroll position.

Example:

const scroller = new SweetScroll();

// CSS Selector of target element
scroller.to('#footer');

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

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

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

// String (Relative position)
scroller.to('+=500');
scroller.to('-=200');

toTop(distance: any, options?: PartialOptions)

Vertical scroll animation to the specified distance.

Example:

scroller.toTop(0);

toLeft(distance: any, options?: PartialOptions)

Horizontal scroll animation to the specified distance.

Example:

scroller.toLeft(1500);

toElement($el: Element, options?: PartialOptions)

Scroll animation to the specified Element.

Example:

scroller.toElement(document.getElementById('content'));

update(options: PartialOptions)

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

Example:

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

stop(gotoEnd: boolean = true)

gotoEnd: {Boolean}

Will stop the current scroll animation.

Example:

scroller.stop(true);

destroy()

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

Example:

scroller.destroy();

Callbacks

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

Example:

const scroller = new SweetScroll({
  // Stop scrolling case of trigger element that contains the `is-disabled` class.
  before: (offset: Offset, $trigger: Element | null, scroller: SweetScroll): boolean | void => {
    console.log('Before!!', offset, scroller);
    if ($trigger && $trigger.classList.contains('is-disabled')) {
      return false;
    }
  },

  // If the `wheel` or `touchstart` event is called
  cancel: (scroller: SweetScroll): void => {
    console.log('Cancel!!', scroller);
  },

  // Scroll animation is complete
  after: (offset: Offset, $trigger: Element | null, scroller: SweetScroll): void => {
    console.log('After!!', offset, $trigger, scroller);
  },

  // Scroll animation is complete (`after` or `cancel`)
  complete: (isCancel: boolean, scroller: SweetScroll): void => {
    console.log('Complete!!', isCancel, scroller);
  },

  // Each animation frame
  step: (time: number, scroller: SweetScroll): void => {
    console.log('step', time, scroller);
  },
});

Extends Class:

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

import SweetScroll, { Offset } from 'sweet-scroll';

class MyScroll extends SweetScroll {
  protected onBefore(offset: Offset, $trigger: Element | null): boolean | void {
    // Stop scrolling case of trigger element that contains the `is-disabled` class.
    console.log('Before!!', offset);
    if ($trigger && $trigger.classList.contains('is-disabled')) {
      return false;
    }
  }

  protected onCancel(): void {
    console.log('Canell!!');
  }

  protected onAfter(offset: Offset, $trigger: Element | null): void {
    console.log('After!!', offset, $trigger);
  }

  protected onComplete(isCancel: boolean): void {
    console.log('Complete!!', isCancel);
  }

  protected onStep(time: number): void {
    console.log('step', time);
  }
}

Browser Support

Works in IE10+, and all modern browsers.

Scrolling with IE9

It is necessary to use polyfill or ponyfill of requestAnimationFrame.

import raf from 'raf';
import SweetScroll from 'sweet-scroll';

SweetScroll.raf = raf;
SweetScroll.caf = raf.cancel;

CHANGELOG

See the CHANGELOG.md

Contibute

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :muscle:

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

Development

We will develop using the following npm scripts.

yarn start

Launch the local server and let the demo run. Opening http://localhost:3000 in your browser.

yarn build

Compile TypeScript and create type definitions.

yarn test

Run unit testing with Jest.

License

MIT © tsuyoshiwada

CHANGELOG

4.0.0

Breaking changes

• Remove find of scrollabl elements logic.
• Change the default value of container from body,html to window.
  • If you specify body,html, it may cause unintended behaviors.
• Remove quickMode options.

Bug fixes

• Fixed a performance problem in which unnecessary matching was execute in onclick handling.
  • Performance improves when there is a lot of DOM.

3.0.1

Bug fixes

• Fix bug that did not scroll when opening devtools #44 (Resolves #38)
  • Big thanks :pray:
    • @adamkarminski
    • @amritk
    • @h6ah4i

3.0.0

TypeScript support and file size down are the main changes. 3.x is a version that contains many destructive changes.

New features

• Support TypeScript :tada:
• Reduce file size by 43.04% !
  • We reviewed many options and functions and cut unnecessary items.
• Add factory method (SweetScroll.create(options?: PartialOptions, container?: string | Element))
  • This is useful if you do not like the coding style using new or you do not need to manage instances.

Breaking changes

• IE9 was excluded from browser support
  • It can correspond by using polyfill of requestAnimationFrame.
• Remove options
  • delay
  • outputLog
• Rename options
  • verticalScroll -> vertical
  • horizontalScroll -> horizontal
  • stopScroll -> cancellable
  • beforeScroll -> before
  • afterScroll -> after
  • canelScroll -> canel
  • completeScroll -> complete
  • stepScroll -> step
• Remove easings (You can use the same easing by passing the function described in README instead.)
  • easeInElastic
  • easeOutElastic
  • easeInOutElastic
  • easeInBack
  • easeOutBack
  • easeInOutBack
  • easeInBounce
  • easeOutBounce
  • easeInOutBounce
• Remove distance argument pattern
  • Object like string (top:0, left:100)
• Rename callback methods
  • beforeScroll -> onBefore
  • afterScroll -> onAfter
  • cancelScroll -> onCancel
  • completeScroll -> onComplete
  • stepScroll -> onStep

Minor changes

• Fixed headers can now be specified from elements. (header)
• Add an instance to the final argument to the optional callback.
  • It corresponds to a problem that can not refer to this when using arrow function.

2.2.0

• Support server-side rendering

2.1.0

New feature

• Add quickMode options
  • Instantly scroll to the destination! (It's recommended to use it with easeOutExpo)

Minor changes

• Update doc
• Update devDependencies

2.0.1

• Change to silent error if container element is not found. (Outputable with outputLog option)
• Minor change in log messages
• Fix demo page can't be viewed locally
• Add loging tests

2.0.0

Breaking changes

Related issues #31. Thanks @nickclaw!!

• Need to initialize an instance after DOMContentLoaded. (So far it has been listening in the library.)
  • In many cases, since there is no need to be initialized before DOMContentLoaded.
• Removed initialized callback & method.
• Removed searchContainerTimeout options.

Minor changes

• Update doc
• Update design of demo page
• Update devDependencies
• Change some of output log
• Update some tests

1.1.0

• Add searchContainerTimeout options
  • We changed the find logic of container element. Because there is a possibility of Timeout Along with it was to add this option.
• Add outputLog options
  • In order to aid in debugging has been added the output of the warning log.
• Add yarn.lock
• Update devDependencies
• Fix some tests

1.0.4

• Fixed a bug related to the container. (ref: #27)

1.0.3

• Fix Chrome/Safari: scroll doesn't fire when browser zoom is less than 100% (ref: #23)

1.0.2

• Add this CHANGELOG.md (ref: #21)
• Change the distribution file in npm (limited to src, test, sweet-scroll.js, sweet-scroll.min.js)
• Update devDependencies

1.0.1

• Fix lint
• Update devDependencies

1.0.0

• Fix issue #17
• Change to npm scripts from Gulp the development environment
• Update eslint config and fix lint
• Refactor for file size reduction.
• Published first major version!!

0.7.1

• Add "push"+"replace" to updateURL options

0.7.0

• Add step callback, and method

0.6.2

• Refactor for initialized

0.6.1

• Fix of viewport and element size
• Bugfix that value of the data-options do not receive
• Add fallback for DOMContentLoaded event
• Some rafactor

0.6.0

• Add preventDefault & stopPropagation options #11

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.

0.4.0

• Add updateURL option

0.3.1

• Bugfix & Update tests
• Change the method of handling a DOMContentLoaded

0.3.0

• Add initialized callback, and method
• Change to initialization of an instance in async

0.2.5

• Refactor for file size reduction.
• Update LICENSE (copyright)

0.2.4

• Add Callback Method tests & refactor

0.2.3

• Add callback methods (beforeScroll, cancelScroll, afterScroll)

0.2.1, 0.2.2

• Fix coordinate calculation of data-scroll-header

0.2.0

• Add toElement method
• Some refactor

0.1.3

• Fix lint & Fix typo in docs

0.1.2

• Refactor

0.1.1

• Fix minimum value of scrollTop and scrollLeft

0.1.0

• Add update method
• Fix Scroll position bug, case of a fixed header specified
• Update passes the trigger elements to the callback

0.0.4

• Fix #1 horizontal scroll bug
• Update Specifies the container in the HTMLElement

0.0.3

• Fix get of scrollabel elements

0.0.2

• Add data options
• Add relative position syntax

0.0.1

• Published