Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lucafalasco/scroll-snap
↯ Snap page when user stops scrolling, with a customizable configuration and a consistent cross browser behaviour
https://github.com/lucafalasco/scroll-snap
scroll scroll-events scrolling snap
Last synced: 9 days ago
JSON representation
↯ Snap page when user stops scrolling, with a customizable configuration and a consistent cross browser behaviour
- Host: GitHub
- URL: https://github.com/lucafalasco/scroll-snap
- Owner: lucafalasco
- License: mit
- Created: 2017-03-03T14:12:01.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T08:33:47.000Z (12 days ago)
- Last Synced: 2024-10-29T09:52:26.807Z (12 days ago)
- Topics: scroll, scroll-events, scrolling, snap
- Language: TypeScript
- Homepage: http://lucafalasco.github.io/scroll-snap/
- Size: 1.53 MB
- Stars: 784
- Watchers: 7
- Forks: 30
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
scroll-snap
---
[](https://www.npmjs.com/package/scroll-snap)
[](https://www.npmjs.com/scroll-snap)
[](https://www.npmjs.com/package/scroll-snap)
Snap page when user stops scrolling, basically implements [CSS Scroll Snap](https://developer.mozilla.org/en-US/docs/Web/CSS/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
```sh
yarn add scroll-snap
```
You can also grab a pre-built version from [unpkg](https://unpkg.com/scroll-snap/dist/index.js)
## Usage
```js
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
```js
{
// attaches the scroll event listener
bind: () => void
// removes the scroll event listener
unbind: () => void
}
```
## Example
```js
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 (custom hook)](https://codesandbox.io/s/scroll-snap-react-hooks-pppv8w?autoresize=1&hidenavigation=1)
## 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