scroll-utility
Table of Contents
- Features
- Installation
- Usage
- Browser Compatibility
- Why?
- License
- Support
Features
- Smooth scroll inside any element in any direction
- Center elements
- Extremely precise
- Handle multiple scroll animation at the time
- High performance
- Detect onScroll events and differentiate between user and utility scroll
- React to elements position changes
- Customize easing function used to animate the scroll
- Typescript support
Installation
It can be installed from npm,
$ npm install --save scroll-utility
or from a cdn at jsdelivr
when downloading from a cdn the package will be globally exported as ScrollUtility
Usage
Basic Scroll
// const Scroll = ScrollUtility.Scroll // if using from a cdn scrollManager.scrollTo50 // scroll to position = 50pxscrollManager.scrollTo50, 1000 // scroll in 1000msscrollManager.scrollTo.element"#some-element" // scroll to "#some-element"scrollManager.scrollTo.element"#some-element", 05 // scroll to "#some-element" and center itscrollManager.scrollTo.element"#some-element", 1, 1000 // scroll to "#some-element" and place it at the bottom of the screen in 1000msscrollManager.scrollTo.scrollSize0 // scroll to the top of the pagescrollManager.scrollTo.scrollSize1 // scroll to the bottomscrollManager.scrollTo.scrollSize05, 1000 // scroll to the middle in 1000msscrollManager.scrollTo.size0 // scroll to top (1st 'screen')scrollManager.scrollTo.size1 // scroll to the 2nd screenscrollManager.scrollTo.size2, 999 // scroll to the 3rd screen in 999ms scrollManager.scrollBy50 // scroll by 50pxscrollManager.scrollBy50, 1000 // scroll by 50px in 1000msscrollManager.scrollBy.element"#some-element" // scroll by "#some-element"'s sizescrollManager.scrollBy.element"#some-element", 05 // scroll by half of the size of "#some-element"scrollManager.scrollBy.element"#some-element", 1, 1000 // scroll by "#some-element"' size in 1000msscrollManager.scrollBy.element"#some-element", 0 // this don't do any scrollscrollManager.scrollBy.scrollSize01 // scroll by 10% of the scroll sizescrollManager.scrollBy.size1 // scroll a screen downscrollManager.scrollBy.size-1 // scroll a screen upscrollManager.scrollBy.size05, 1000 // scroll half a screen down
That's just a quick reference cheat sheet of how to use scroll-utility, if you want to learn more keep reading :)
Creating a scroll manager
scroll wrapper
The element option when creating a 'scrollManager' indicates the element in which the scroll will take place, by default the window
scrollManager = new Scroll //same as abovescrollManager = new Scroll //same as abovescrollManager = new Scroll //same as abovescrollManager = new Scroll //same as above scrollManager = new Scroll // create a scrollManager for the "#some-element"scrollManager = new Scroll // same as above
direction
The horizontal option indicates the direction when scrolling, by default vertical
scrollManager = new Scroll // same as abovescrollManager = new Scroll // create a scrollManager with horizontal scroll
onScroll callback
let scrollManager = // no callback by default :)scrollManager = { console if external // external === true if the scroll was triggered by other means (the user with the mouse or other js running in the browser) } // can be changed later:scrollManager console // callback changedscrollManageronScroll = null // go back to default config :)
default duration
The duration option indicates the default duration of the scroll animations in milliseconds, by default 0
scrollManager = new Scroll // 350ms scroll duration // can be changed later:scrollManager.duration = 1000 // 1 second scroll duration
easing
The easing option indicates the default animation of the scroll, which is by default inOutQuad
scrollManager = new Scroll // same as above // can also be changed later:scrollManager.easing =
Here are some more easing functions
Scrolling
scrollBy
scrollBy will accept a value (the number of px to scroll down), a duration (to override the default duration), and a easing function (to override the default one).
If the value in negative it will scroll up
scrollManager.scrollBy50 // scroll 50px downscrollManager.scrollBy-50 // scroll 50px upscrollManager.scrollBy50, 1000 // scroll by 50px in 1000msscrollManager.scrollBy50, 1000, customEasingFunction // it can also be specified an easing function just for that scroll animation
scrollBy element
The 1st parameter of scrollBy.element is the element whose size will be used to scroll, the rest of parameters same as plane scrollBy
scrollManager.scrollBy.element"#some-element" // scroll by "#some-element"'s sizescrollManager.scrollBy.element"#some-element", 05 // scroll by half of the size of "#some-element"scrollManager.scrollBy.element"#some-element", -1, 1000 // scroll by "#some-element"' size up in 1000msscrollManager.scrollBy.element"#some-element", 1, 1000, customEasingFunction // scroll by "#some-element"' size in 1000ms with a customEasingFunction
scrollBy size
Here the size is the size of the scroll container, and the value passed is a modifier, been 1 the full size, 0.5 half, and a negative value will mean the scroll will be up instead of down (or left instead of right)
scrollManager.scrollBy.size1 // scroll a screen downscrollManager.scrollBy.size-1 // scroll a screen upscrollManager.scrollBy.size05, 1000 // scroll half a screen down
See size
scrollBy scrollSize
scrollManager.scrollBy.scrollSize01 // scroll by 10% of the scroll size
See scrollSize
scrollTo
scrollTo will accept a value (the position to scroll to), a duration (to override the default duration), and a easing function (to override the default one).
scrollManager.scrollTo50 // scroll to position = 50pxscrollManager.scrollTo50, 1000 // scroll in 1000ms
scrollTo element
The 1st parameter of scrollTo.element is the element whose position will be used to scroll, the rest of parameters same as plane scrollTo
For the value used to center the element, it matches the same criteria used in getRelativeElementPosition
scrollManager.scrollTo.element"#some-element" // scroll to "#some-element"scrollManager.scrollTo.element"#some-element", 05 // scroll to "#some-element" and center itscrollManager.scrollTo.element"#some-element", 1, 1000 // scroll to "#some-element" and place it at the bottom of the screen in 1000ms
scrollTo size
Pretty much the same as scrollBy.size, except it scrolls to instead of by.
scrollManager.scrollTo.size0 // scroll to top (1st 'screen')scrollManager.scrollTo.size1 // scroll to the 2nd screenscrollManager.scrollTo.size2, 999 // scroll to the 3rd screen in 999ms
See size
scrollTo scrollSize
Same as scrollBy.scrollSize, except it scrolls to instead of by.
scrollManager.scrollTo.scrollSize0 // scroll to the top of the pagescrollManager.scrollTo.scrollSize1 // scroll to the bottomscrollManager.scrollTo.scrollSize05, 1000 // scroll to the middle in 1000ms
See scrollSize
Computed values
scrollPosition
scrollManager.scrollPosition // current position of the scroll (direction depends of the default value passed in the constructor)
size
scrollManager.size // the size of the element (excluding its borders and scrollbar's size)
scrollSize
scrollManager.scrollSize // the total scroll you can do, (scrollHeight - height (or width depending on the direction))
relativeElementPosition
if relativePosition < -1 if relativePosition > -1 && relativePosition < 0 if relativePosition > 0 && relativePosition < 1 if relativePosition > 1 && relativePosition < 2 if relativePosition > 2
Browser Compatibility
Test are made using automate testing with Browserstack for open source.
Why?
There are a lot of packages about smooth scrolling, so, what's the difference?
Well, the main idea is to be able to stack multiple scroll animations together, and with high precision. That is not an extra feature, that's what this package does, you can trigger multiple animations to several places, and it will be as precise as it can be.
License
Support
This project is free and open-source, so if you think this project can help you or anyone else, you should star it in github Also feel free to open an issue if you have any idea, question, or you've found a bug. Any feedback is good support