JavaScript Plugin For Smooth Scroll Snapping - panelSnap

File Size: 15.5 KB
Views Total: 40284
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
JavaScript Plugin For Smooth Scroll Snapping - panelSnap

panelSnap is a JavaScript plugin (jQuery is optional) that allows to snap to blocks of content when you scroll through a web page or parts of it.

Great for creating one page scroll websites or single page web applications. Also compatible with React & Vue apps.

See also:

How to use it:

1. Install and import the panelSnap with NPM.

# NPM
$ npm i panelsnap --save
import PanelSnap from 'panelsnap';

2. Or include the panelSnap's JavaScript on the page.

<!-- jQuery Is Optional -->
<script src="/path/to/cdn/jquery.min.js"></script>
<!-- panelSnap Plugin -->
<script src="/path/to/lib/panelsnap.umd.js"></script>

3. Create a set of panels (content sections) you want to scroll through.

<section>
  Section 1
</section>

<section>
  Section 2
</section>

<section>
  Section 3
</section>

...

4. Make the content sections full page.

section {
  position: relative;
  overflow: hidden;
  width: 100%;
  min-height: 100vh;
}

5. Enable the plugin and done.

new PanelSnap();

5. Possible options to customize the plugin.

new PanelSnap({

    // parent container
    container: document.body,

    // panel selector
    panelSelector: '> section',

    // threshold
    directionThreshold: 50,

    // scroll delay
    delay: 0,

    // duration in milliseconds
    duration: 300,

    // easing function
    easing: function(t) { return t }
    
});

6. API methods.

const instance = new PanelSnap();

// scroll to a specific element
instance.snapToPanel(element);

// destroy the instance
instance.destroy();

7. Event handlers.

const instance = new PanelSnap();

instance.on('activatePanel', function(){
  // do something
})

instance.on('snapStart', function(){
  // do something
})

instance.on('snapEnd', function(){
  // do something
})

instance.on('snapStop', function(){
  // do something
})

Changelog:

2021-06-10

v1.3.0 (2019-07-31)

  • added destroy method
  • doc updated

v1.2.2 (2019-07-30)

  • utilities: exclude scrollbars from body container rect
  • utilities: use documentElement instead of scrollingElement

2018-05-13

  • chore: resolve casing inconstencies
  • feat: allow interruption from mousewheel

2018-05-10

  • refactor: reserve scrollTimeout variable on init

2018-05-09

  • fix: only take directionThreshold into account when actually snapping

2018-04-24

  • Prevent snapping when in large panel

2018-04-23

  • fix: Fix getTargetScrollTop not working for body

2018-04-18

  • Fix getElementsInContainerViewport not returning elements when larger than the viewport.

2018-04-13

  • Add snapToPanel method

2018-04-09

  • JavaScript & CSS updated

2018-03-10

  • JavaScript & CSS updated

2018-01-22

  • feat(snapping): Snap to bottom when scrolling up into large panel.

2017-09-17

  • refer document.scrollingElement as the snap container in browsers that support it when the container is body, and don't overwrite it to be body in Chrome as Chrome 61 now supports this properly

v0.15.1 (2015-11-09)

  • Improve panel finding logic in snapTo method.
  • Code cleanup.
  • Update demo styling.

v0.14.0 (2015-01-23)

  • Added easing option to panel snap

v0.13.0 (2014-12-10)

  • Added easing option to panel snap

v0.12.0 (2014-04-25)

  • Minor fixes in the scrolling logic.

v0.11.0 (2014-01-22)

  • version update.

v0.10.3 (2014-01-20)

  • Makes snapToPanel require a valid target. 

v0.9.2 (2013-10-25)

  • Reformats plugin and moves custom events into plugin file.

v0.9.1 (2013-09-04)

  • Reformats plugin and moves custom events into plugin file.

This awesome jQuery plugin is developed by guidobouman. For more Advanced Usages, please check the demo page or visit the official website.