ASScroll is a hybrid smooth scroll setup that combines the performance gains of virtual scroll with the reliability of native scroll.
Advantages over pure virtual scroll:
- accessibility / keyboard friendly (without manual key detection)
- no special cases to cater for when detecting key detection (i.e. pressing space in a form input)
- doesn't stop working when hovering over an iframe
- handles hardware that doesn't fire the 'wheel' event i.e. Windows trackpads in Edge + IE
Coming Soon!
- Install
- Basic Setup
- Options
- Methods
- Properties
- Events
- Custom Scrollbar
- External RAF Usage
- External Resize Usage
npm i -D @ashthornton/asscroll or yarn add @ashthornton/asscroll
- Add a class of
.asscroll-containerto the parent element of the content to be smooth scrolled
<body>
<div class="asscroll-container">
Content
</div>
</body>- Import and initialise in Javascript
import ASScroll from '@ashthornton/asscroll'
const smoothScroll = new ASScroll( options = {} )
smoothScroll.enable()Passed as an object through to the ASScroll constructor. Defaults shown next to option names.
element: .asscroll-container - The parent element of the content to be smooth scrolled
ease: 0.1 - Smooth scroll easing
customScrollbar: false - Enable the use of a custom scrollbar
scrollbarEl: .asscrollbar - The parent element of the custom scrollbar
scrollbarHandleEl: .asscrollbar__handle - The grabbable bar element in the custom scrollbar
scrollbarStyles: true - Include the default scrollbar CSS
disableNativeScrollbar: true - Disables the browser's scrollbar
disableRaf: false - Disable internal requestAnimationFrame loop in order to use an external one
disableResize: false - Disable internal resize event on the window in order to use an external one
enable( restore = false, reset = false, newTarget = false ) - Enable scroll
restore- restores the previous scroll position whendisable()was last calledreset- force resetting scroll position to 0newTarget- pass in a selected DOM node to set a new scroll target i.e. when loading in a new page via Highway.
disable() - Disable scroll
onRaf() - Trigger the internal animation frame loop
onResize( windowWidth = null, windowHeight = null ) - Trigger the internal resize event
- Pass window size manually to this function if you're already getting it in your own resize handler.
scrollTo( y ) - Scroll to a y coordinate on the page
on( event, callback ) - Add a callback to an event
off( event, callback ) - Remove a callback from an event
scrollPos - returns the current target scroll position
smoothScrollPos - returns the current smoothed scroll position
on('scroll', scrollPos => {}) - Fires on page scroll. Provides current scroll position.
on('raf', ({ scrollPos, smoothScrollPos }) => {}) - Fires on requestAnimationFrame. Continuously provides the target scroll position and the current smoothed scroll position.
When customScrollbar is enabled in the options, a default set of styles will get added to the page that match the following HTML:
<div class="asscrollbar"><div class="asscrollbar__handle"><div></div></div></div>Add this HTML anywhere outside of the main .asscroll-container element - just before the closing </body> tag works fine.
You can change the classes that are used by changing the scrollbarEl and scrollbarHandleEl options.
You can use your own styles by setting the scrollbarStyles option to false.
⚠ Note: These styles are added via JS so will only be applied after JS has loaded. This may cause the native scrollbar to show for a moment before the styles are added resulting in a jump of the page.
You can include the styles necessary to hide the native scrollbar in your CSS by copy and pasting the contents of /css/index.css or simply by importing them into your CSS setup. For example:
@import '~@ashthornton/asscroll/css'
This won't be an issue with the custom scrollbar styles as you can't smooth scroll until JS is ready anyway.
const smoothScroll = new ASScroll({
disableRaf: true
})
// Regular RAF setup
requestAnimationFrame(onRaf)
function onRaf() {
smoothScroll.onRaf()
requestAnimationFrame(onRaf)
}
// Use with GSAP's internal RAF
gsap.ticker.add(smoothScroll.onRaf)
smoothScroll.enable()const smoothScroll = new ASScroll({
disableResize: true
})
window.addEventListener('resize', () => {
// trigger other resize logic
smoothScroll.onResize()
})
smoothScroll.enable()- Handle tabbing focus scroll
- Handle anchor link scroll
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent