Skip to main content

ScrollTo

Quick Start

Register​

 gsap.registerPlugin(ScrollToPlugin)

Minimal usage​

//scroll to 400 pixels down from the top
gsap.to(window, { duration: 2, scrollTo: 400 });
tip

If you want to do scroll-driven animations where things get triggered at certain scrollbar positions, use the ScrollTrigger plugin.

Description​

Animates the scroll position of the window (like doing window.scrollTo(x, y)) or a DOM element (like doing myDiv.scrollTop = y; myDiv.scrollLeft = x;).

danger

using alongside scroll-behavior: smooth in CSS will cause conflicts

To scroll the window to a particular position, use window as the target of the tween like this:

//scroll to 400 pixels down from the top
gsap.to(window, { duration: 2, scrollTo: 400 });

//or to scroll to the element with the ID "#someID" (as of GSAP 1.19.0):
gsap.to(window, { duration: 2, scrollTo: "#someID" });

To tween the content of a div, make sure you've set the overflow: scroll on the div and then:

//scroll to 250 pixels down from the top of the content in the div
gsap.to(myDiv, { duration: 2, scrollTo: 250 });

You can define an x or y value or both (to scroll on both the x and y axis). For example, to scroll to 400 pixels from the top and 200 pixels from the left, do this:

gsap.to(myDiv, { duration: 2, scrollTo: { y: 400, x: 200 }, ease: "power2" });

You can also optionally pass offsetX and/or offsetY numeric values if you want to offset the destination from the element.

//scroll #someID into view with 50 pixels from the top (like a margin)
gsap.to(window, { duration: 2, scrollTo: { y: "#someID", offsetY: 50 } });

The demo below uses the offsetY so that each section scrolls into view just under the navigation. Click the section buttons in the demo below. Check out the JS source.

loading...

To have ScrollToPlugin automatically sense if the scroll position was changed outside of itself (like if the user manually started dragging the scrollbar mid-tween) and cancel that portion of the tween, set autoKill: trueinside the scrollTo object, like:

gsap.to(myDiv, {
  duration: 2,
  scrollTo: { y: 400, autoKill: true },
  ease: "power2",
});

If you would like to detect when autoKill gets triggered you can define an onAutoKill callback.

gsap.to(window, {
  duration: 2,
  scrollTo: { y: 300, autoKill: true, onAutoKill: myAutoKillFunction },
});

function myAutoKillFunction() {
  alert("autoKill");
}

To scroll to the maximum scroll position, use the string "max" as the value, like this:

gsap.to(myDiv, { duration: 2, scrollTo: { y: "max" } });

If you don't wrap the value in an object, it will assume you want to scroll in the "y" direction, so these two lines are functionally equivalent:

gsap.to(myDiv, { duration: 2, scrollTo: { y: "max" } });
gsap.to(myDiv, { duration: 2, scrollTo: "max" });

Here's a basic example using anchors:

loading...

FAQ's​

How do I include ScrollToPlugin in my project?

See the installation page for all the options (CDN, NPM, download, etc.) where there's even an interactive helper that provides the necessary code. Easy peasy. Don't forget to register ScrollToPlugin like this in your project:

gsap.registerPlugin(ScrollToPlugin)

Is this included in the GSAP core?

No, you must load/import it separately

Is this only for Club GSAP members?

No, it's available to everyone for free! But Club GSAP is pretty awesome...just sayin'.

It works fine during development, but suddenly stops working in the production build! What do I do?

Your build tool is probably dropping the plugin when tree shaking and you forgot to register ScrollToPlugin (which protects it from tree shaking). Just register the plugin like this:

gsap.registerPlugin(ScrollToPlugin)

Is it bad to register a plugin multiple times?

No, it's perfectly fine. It doesn't help anything, nor does it hurt.

Contents