Simple Scrollspy

Simple scrollspy is a lightweight javascript library without jQuery, no dependencies. It is used to make scrollspy effect for your menu, table of contents, etc. Only 1.4Kb.

Examples:

Install

Using NPM package

Install NPM package - https://www.npmjs.com/package/simple-scrollspy:

npm install simple-scrollspy

Using CDN

cdnjs

The simple-scrollspy library is available on cdnjs. For instance:

<script src="https://cdnjs.cloudflare.com/ajax/libs/simple-scrollspy/2.4.1/simple-scrollspy.min.js" integrity="sha512-NNb5TgmE+7PHedvAWwPKZ/ukCGJciTHZ23ghPriEeEfcGySDBm9zIrjaXp/WNAUcVYhi5XhJ1rHveDKR35CInw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

jsDelivr

The simple-scrollspy can be installed using jsDelivr. For instance:

<script src="https://cdn.jsdelivr.net/npm/simple-scrollspy@2.5.3/demo/dist/simple-scrollspy.min.js"></script>

Using `simple-scrollspy.min.js` file

The simple-scrollspy.min.js file is available for download with each release. To obtain the most recent version, please visit the latest release page on GitHub.

<script src="/path/to/dist/simple-scrollspy.min.js"></script>

Usages

Easy for using, syntax just like this:

scrollSpy(menuElement, options)

This little plugin will add active class into your existing menu item when you scroll your page to a matched section by ID. If you are giving it a try, make sure that you:

Added CSS for active class in your menu item. Because this plugin doesn’t include CSS.
Added ID for your sections. Example: <section id="first-section">...</section>
Added an attribute which is a section ID into your menu items. The default value is href. Example: "href"="#first-section". You also replace href with the other name by hrefAttribute in options.

Arguments

The menuElement is a query selector for your menu. It is String or HTMLElement instance.
The options is optional. It types of Object contains the properties below:

Name	Type	Default	Description
`sectionClass`	String	`.scrollspy`	Query selector to your sections
`menuActiveTarget`	String	`li > a`	Element will be added active class
`offset`	Number	0	Offset number
`hrefAttribute`	String	`href`	The menu item’s attribute name which contains section ID
`activeClass`	String	`active`	Active class name will be added into `menuActiveTarget`
`scrollContainer`	String, HTMLElement	`window`	User Defined Scrolling Container
`smoothScroll`	Boolean, Object	`false`	Enable the smooth scrolling feature
`smoothScrollBehavior`	Function	`undefined`	Define your smooth scroll behavior
`onActive`	Function	`undefined`	Trigger after the menu item is added the `activeClass` class

ES6 example

import scrollSpy from 'simple-scrollspy'

const options = {
  sectionClass: '.scrollspy',           // Query selector to your sections
  menuActiveTarget: '.menu-item',       // Query selector to your elements that will be added `active` class
  offset: 100,                          // Menu item will active before scroll to a matched section 100px
  scrollContainer: '.scroll-container', // Listen scroll behavior on `.scroll-container` instead of `window`
}

// init:
scrollSpy(document.getElementById('main-menu'), options)

// or shorter:
scrollSpy('#main-menu', options)

Inject static file

<script src="/path/to/dist/simple-scrollspy.min.js"></script>
<script>
  window.onload = function () {
    scrollSpy('#main-menu', {
      sectionClass: '.scrollspy',
      menuActiveTarget: '.menu-item',
      offset: 100,
      // smooth scroll
      smoothScroll: true,
      smoothScrollBehavior: function(element) {
        console.log('run "smoothScrollBehavior"...', element)
        element.scrollIntoView({ behavior: 'smooth' }) // default behavior
      }
    })
  }
</script>

Smooth scroll

import jumpTo from 'jump.js'

scrollSpy('#main-menu', {
  // ....,

  // enable smooth scroll:
  // - true: enable with the default scroll behavior
  // - false: disable this feature
  // - object: enable with some options that will pass to `Element.scrollIntoView` or `smoothScrollBehavior`
  //   + Default behavior: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
  //   + Jump.js: https://www.npmjs.com/package/jump.js
  smoothScroll: true,

  // customize scroll behavior,
  // - default: Element.scrollIntoView({ ...smoothScroll, behavior: 'smooth' })
  // - customize: you can define your scroll behavior. Ex: use `jump.js`, jQuery, .etc
  smoothScrollBehavior: function(element, options) {
    // use `jump.js` instead of the default scroll behavior
    jumpTo(element, {
      duration: 1000,
      offset: -100,
    })
  }
})

Development

$ yarn install
$ yarn dev

Build

$ yarn build

or:

$ npm run build

The dist folder is automatically created and includes the file simple-scrollspy.min.js

Note

Feel free to make a pull request if you can, and create a Github Issue if you come across one.
Don’t forget to give it a star if you feel that the library is helpful to you. It may save somebody a lot of trouble someday.

Support / Donate

Helpful links

Licence

MIT