Skip to content

ocsal/scroll-snap

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

scroll-snap


npm npm npm downloads

Snap page when user stops scrolling, basically implements CSS Scroll Snap, adding a customizable configuration and a consistent cross browser behaviour.

  • Works in all modern browsers
  • requestAnimationFrame for 60fps
  • Customizable settings (including easing functions)
  • No additional dependencies
  • No extra stylesheet

Installation

yarn add scroll-snap

You can also grab a pre-built version from unpkg

Usage

createScrollSnap(element, settings, [callback])

Arguments

element: HTMLElement

The HTML DOM Element to attach the scroll listener to.

settings: Settings

A configuration object consisting of one or more of the following keys:

snapDestinationX: string | number

Snap destination for x axis, should be a valid css value expressed as px | % | vw | vh

snapDestinationY: string | number

Snap destination for y axis, should be a valid css value expressed as px | % | vw | vh

timeout: number

Time in ms after which scrolling is considered finished
[default: 100]

duration: number

Duration in ms for the smooth snap
[default: 300]

threshold: number

Threshold to reach before scrolling to next/prev element, expressed as a percentage in the range [0, 1]
[default: 0.2]

snapStop: boolean

When true, the scroll container is not allowed to "pass over" the other snap positions
[default: false]

easing: (t: number) => number

Custom easing function
@param t: normalized time typically in the range [0, 1]
[default: easeInOutQuad]

For reference: https://gist.github.com/gre/1650294

callback: () => void [Optional]

Optional callback to execute once the animation ends.

Returns

An object including two handlers to manually attach and remove the scroll event listener

{
  // attaches the scroll event listener 
  bind: () => void 
  // removes the scroll event listener
  unbind: () => void 
}

Example

import createScrollSnap from 'scroll-snap'

const element = document.getElementById('container')

const { bind, unbind } = createScrollSnap(element, {
  snapDestinationX: '0%',
  snapDestinationY: '90%',
  timeout: 100,
  duration: 300,
  threshold: 0.2,
  snapStop: false,
  easing: easeInOutQuad,
}, () => console.log('element snapped'))

// remove the listener 
// unbind();

// re-instantiate the listener 
// bind();

Usage with React

Contributing

git clone https://github.com/lucafalasco/scroll-snap.git
cd scroll-snap
yarn install

Start the testing environment from playground/:

yarn start

Build lib for production:

yarn build

License

MIT