Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alexiscolin/smooth-scrollr
đź–±Simple smooth scrolling in JS
https://github.com/alexiscolin/smooth-scrollr
Last synced: about 1 month ago
JSON representation
đź–±Simple smooth scrolling in JS
- Host: GitHub
- URL: https://github.com/alexiscolin/smooth-scrollr
- Owner: alexiscolin
- License: mit
- Created: 2018-03-15T22:08:02.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-06-12T11:21:13.000Z (over 1 year ago)
- Last Synced: 2024-10-05T06:34:06.915Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 125 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]
🖱️ smooth-scrollr
Simple smooth scrolling module based on fake scroll events (aka wheel and touch and keyPress...).
View Demos
·
Report Bug
·
Request Feature
Table of Contents
## About The Project
### Built With
- [JS ES6/7/8](https://www.ecma-international.org/technical-committees/tc39/)
- [Babel](https://babeljs.io/)
- [Webpack](https://webpack.js.org/)
## Getting Started
Made as a prototype reveal based class, initialize the module to use it.
### Prerequisites
This is an example of how to list things you need to use the software and how to install them.
- npm
```sh
npm i smooth-scrollr@latest
```
- yarn
```sh
yarn add smooth-scrollr
```
### Installation
1. Clone the repo
```sh
git clone https://github.com/alexiscolin/smooth-scrollr.git
```
2. Install NPM packages
```sh
npm install
```
## Usage
Basic usage :
```html
...
```
_Note: data-scroll-container are optional but recommended to improve long page performance._
```javascript
import { SmoothScrollr } from "smooth-scrollr";
const opts = {
section: document.querySelector("#section"),
speed: 0.8,
fixedClass: "fixedClass",
};
const smoothscroll = new SmoothScrollr(opts);
```
_Note: 'fixedClass' is optional and set the class you define to block real scroll to the right container. Inline styles are used if not definied_
### ...Or in a global way (without bundler)
Get the `smooth-scrollr.min.js` file inside the `dist` folder. Then, use it in the html file :
```html
(function () {
const opts = {
/*opts here */
};
var scroll = new SmoothScrollr(opts);
})();
```
## Options and Settings
| Option | Type | Default | Description | |
| ------------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `section` | `object` | `body` | DOM section that you want to make scrollable or data-scroll-containers parent if you want to use multi wrapper option (make sure the parent wrap all children in horizontal scroll case). | |
| `listened` | `object` | `config.section` | DOM section that will be used as scroll listener. | |
| `direction` | `string` | `vertical` | `vertical` | `horizontal` Scroll direction: If horizontal, avoid to set section width in any value other than `auto` in order to create a container that is bigger than the viewport. |
| `speed` | `number` | `1` | Speed value on the range 0-1 that is slowing the smoothing effect. | |
| `delay` | `number` | `.1` | Easing value between 0 & 1 | |
| `fixedClass` | `string` | | The class you want to set in order to fix the viewport (at least you need `overflow: hidden` and `height: 100%` on the container and `overscroll-behavior: none` or `overflow: hidden` on the body). | |
| `touch` | `boolean` | `false` | Enable smooth scroll on touch event | |
| `touchSpeed` | `number` | `1.5` | Scrolling speed on touch event | |
| `jump` | `number` | `110` | Scrolling step on keyPress event | |
| `multFirefox` | `number` | `15` | Scrolling speed on Firefox | |
| `preload` | `boolean` | `true` | Enable preload media function in order to resize page after async | |
| `resize` | `boolean` | `true` | Enable auto resize | |
| `initFuncs` | `array` | | Array of functions that must be fired after the instance has been initialised. If `preload`, init takes place after the event | |
## Element attribute
- `data-scroll-container` : create a scrollable container inside the `section`. Splitting the page into smaller container is good to improve performance. Only the viewed container will move, so lighten containers will move one after the other. This is totaly optional.
## Methods
| Methods | Description | Arguments |
| --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrollTo` | In order to force scroll to a location on the webpage. | `dir` : _(number)_ - the position in px you want to go on the page
- `imediate` : _(boolean - default: false)_ - go with/without smooth effect
- `cb` : _(function - default: undefinied)_ - callback function called once the move is done |
| `scrollOf` | In order to scroll from a specific number of pixel. | `path` : _(number)_ - the distance in px you want the page go through. Return the scroll position
- `imediate` : _(boolean - default: false)_ with/without smooth effect
- `cb` : _(function - default: undefinied)_ - callback function called once the move is done |
| `getSize` | In order to get the scroller container size. | |
| `on` | In order to add a listener function on a specific scroll event. | `event` : _(string)_ - the instance event you want to listen (see the list below)
`callback` : _(function)_ - the function you want to trigger when the event is dispatched
`context` : _(object - default : section)_ the content you want to listen (you should avoid to use it unless you know what you do) |
| `off` | In order to remove a listener function on a specific scroll event. | `event` : _(string)_ - the instance event you want to remove a listener (see the list below)
`callback` : _(function)_ - the function you want to remove (use the same as you set to add the listener)
`context` : _(object - default : section)_ the content you want to listen (you should avoid to use it unless you know what you do) |
| `resize` | In order to recalculate scroll container. | |
| `destroy` | In order to destroy scroll container. | |
| `preventScroll` | In order to freeze scrolling movement. | `state` : _(boolean)_ - freeze or unfreeze scroll event
`prevent` : _(boolean - default: true)_ - freeze the listener or the move effect |
### Exemples :
#### Force imediate scroll
```javascript
smoothscroll.scrollTo(0, true); // go to the top without smoothing
```
#### Smooth scroll of 200px
```javascript
smoothscroll.scrollFrom(200, false); // go 200px forward smoothly
```
#### Add a callback to scroll instance event
```javascript
const callback = () => {
console.log("yeah!!");
};
smoothscroll.on("scroll", callback); // 'yeah!!` appears in the console during the scroll.
// You can access scroll position as parameter in callbak function (scroll event only)
```
#### Remove a callback to scroll instance event
```javascript
smoothscroll.off("scroll", callback); // use the same previous callback function
```
#### Destroy scroll instance
```javascript
smoothscroll.destroy(); // all events are removed and the instance has been killed
```
## Events
| Event | Description |
| ----------------- | -------------------------------------------------------------------------------- |
| `scroll` | trigger during scroll |
| `collisionTop` | trigger when the scroll is at top of the page |
| `collisionBottom` | trigger when the scroll is at bottom of the page |
| `collisionEnded` | trigger once when the scroll stop to be blocked by the collision with page edges |
## Roadmap
- [x] ScrollTo method
- [x] destroy method
- [x] horizontal scroll support
- [ ] add a scroll bar
## Who is Using
- [jaunebleu.co](https://jaunebleu.co/)
- [gabriel-cuallado.com](https://gabriel-cuallado.com/)
## Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. See [LICENCE FILE](https://github.com/alexiscolin/smooth-scrollr/blob/master/LICENSE) for more information.
## Contact
Alexis Colin - [linkedin](https://www.linkedin.com/in/alexiscolin/) - [email protected]
Project Link: [https://github.com/alexiscolin/smooth-scrollr](https://github.com/alexiscolin/smooth-scrollr)
[contributors-shield]: https://img.shields.io/github/contributors/alexiscolin/smooth-scrollr.svg?style=for-the-badge
[contributors-url]: https://github.com/alexiscolin/smooth-scrollr/graphs/contributors
[issues-shield]: https://img.shields.io/github/issues/alexiscolin/smooth-scrollr.svg?style=for-the-badge
[issues-url]: https://github.com/alexiscolin/smooth-scrollr/issues
[license-shield]: https://img.shields.io/github/license/alexiscolin/smooth-scrollr.svg?style=for-the-badge
[license-url]: https://github.com/alexiscolin/smooth-scrollr/blob/master/LICENSE
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/alexiscolin