Chapter 313: ScrollSmoother

Core Idea

added in v3.10.0

Key Concepts

• Uses the browser's native scroll; no "fake" scrollbars.
• Add a parallax effect by defining a data-speed attribute on any element, like data-speed="0.5" would make that element "scroll" at half-speed while it's in the viewport. It arrives at its normal position in the document flow when it's centered vertically.
• Put a larger image/element inside a container that has overflow: hidden and then set the child's data-speed="auto" and it'll automatically calculate exactly how far it can move inside that container (parallax).
• Make an element appear to lag behind, taking a certain amount of time to "catch up" to the smoothed scroll position. It's a really fun effect! Simply define a data-lag attribute, like data-lag="0.5" would take 0.5 seconds to "catch up".
• ScrollSmoother is seamlessly integrated with ScrollTrigger and GSAP for mega-robust animation capabilities.
• Set paused(true) to completely halt scrolling (users can't even drag the scrollbar) - great for modals.
• The normalizeScroll: true feature prevents [most] mobile browser address bars from hiding/showing (resizing the viewport), stops overscroll behavior, and solves multi-thread synchronization challenges!
• A side benefit of using ScrollSmoother is that it avoids issues caused by browser multi-threading, like the small jump that sometimes happens when pinning/unpinning, or the occasional "jitter" of a pinned element in certain rare scenarios. You can even set normalizeScroll: true to avoid common problems like the hiding/showing of the address bar on mobile browsers, plus it'll work around iOS Safari bugs that occasionally cause jitter. See ScrollTrigger.normalizeScroll() for details.

Code Examples

gsap.registerPlugin(ScrollSmoother)

• What it demonstrates: typical usage of ScrollSmoother in a GSAP animation.

Reference Tables

#### .progress : Number	The progress value of the overall page scroll where 0 is at the very top and 1 is at the very bottom and 0.5 is halfway scrolled. This value will animate during the smooth scrolling and end when the onStop fires.
#### .scrollTrigger : ScrollTrigger	The ScrollTrigger instance that ScrollSmoother created internally to manage the smooth scrolling effect of the page.
#### .vars : Object	The configuration object passed into the ScrollSmoother.create() initially.

#### .content( element:String | Element ) : Element | self	Gets/Sets the content element.
#### .effects( targets:String | Element | Array, config:Object | null ) : Array	Adds parallax elements that should be managed by the ScrollSmoother
#### .getVelocity( ) : Number	Returns the current velocity of the smoothed scroll in pixels-per-second
#### .kill( ) ;	Kills the entire ScrollSmoother as well as any effects that were applied.
#### .offset( target:String | Element, position:String ) : Number	Calculates the numeric offset (scroll position in pixels) that corresponds to when a particular element reaches the specified position like:
#### .paused( pause:Boolean ) : Boolean | self	Gets/Sets the paused state - if true, nothing will scroll (except via scrollTop() or scrollTo() on this instance).
#### .scrollTo( target:Number | String | Element, smooth:Boolean, position:String ) ;	Scrolls to a particular position or element
#### .scrollTop( position:Number ) : Number | void	Immediately gets/sets the scroll position (in pixels).
#### .smooth( duration:Number ) : Number | self	Gets/Sets the number of seconds it takes to catch up to the scroll position (smoothing).
#### ScrollSmoother.create( ) ;
#### ScrollSmoother.get( ) : ScrollSmoother	Returns the ScrollSmoother instance (if one has been created). There can only be one instance at any given time.
#### .wrapper( element:String | Element ) : Element | self	Gets/Sets the wrapper element.

Key Takeaways

1. Uses the browser's native scroll; no "fake" scrollbars.
2. Add a parallax effect by defining a data-speed attribute on any element, like data-speed="0.5" would make that element "scroll" at…
3. Put a larger image/element inside a container that has overflow: hidden and then set the child's data-speed="auto" and it'll…
4. Make an element appear to lag behind, taking a certain amount of time to "catch up" to the smoothed scroll position.
5. ScrollSmoother is seamlessly integrated with ScrollTrigger and GSAP for mega-robust animation…

Connects To

• ScrollTrigger: related GSAP concept
• paused(true): see ch319 — .paused
• ScrollTrigger.normalizeScroll(): see ch365 — ScrollTrigger.normalizeScroll
• effects(): see ch315 — .effects
• .progress: see ch320 — .progress