Triggers classes on html elements based on the scroll position. It makes use of requestAnimationFrame so it doesn't jack the users scroll, that way the user / browser keeps their original scroll behaviour. Animations run when the browser is ready for it.
How to use?
It's quite simple, just add the
ScrollTrigger.min.js file to your HTML page. Then construct a new ScrollTrigger instance when the page has loaded. Like so:
That's how simple it can be. A more advanced example would be:
The init call takes 3 parameters, the first is a default set of options. The last two are the
scrollIn parameters. These are optional.
bindTo parameter is the HTML element where the triggers should be fetched from, this usually is
document.body but could specify to a certain element.
scrollIn parameter is the element to get the scroll position from, by default this is
window, but it could be a scrolling div etc.
Now add the
data-scroll attribute to the HTML element you want to animate:
When you scroll the page, and the element is visible in the viewport, it will add the
visible class. If it's out of the viewport the
invisible class is added. Now you can define those classes in your css file and add animations to them, like so:
Now when you scroll the page, the elements that 'come in' to the viewport fade in. A really basic example.
data-scroll attribute can take a couple of options, in contrast to v0.1, the position of the options are not strict. So you can place them anywhere inside the
|toggle()||CSS Classes||These are the classes that ScrollTrigger changes, a replacement for the default
|offset()||Pixels||This is a custom offset you can add to the element, this is nice for tuning animations. It takes 2 required parameters, the x and y offset.||
|addWidth||Boolean||This adds the offsetWidth of the element to the offset, so the
|addHeight||Boolean||This adds the offsetHeight of the element to the offset, so the
|centerHorizontal||Boolean||This adds the half of the offsetWidth to the offset, so the
|centerVertical||Boolean||This adds the half of the offsetHeight to the offset, so the
|once||Boolean||This makes sure the animation only runs once, if you add a callback that will also only run once.||
For advanced examples on how to use the options, check out the
example folder. Especially the
You can add callbacks to the show and hide events, e.g. when an element comes into the viewport and when it goes out. You do this by adding the
data-scroll-showCallback and / or the
data-scroll-hideCallback tags. We avoid using
eval so the callback needs to be in the (global)
window scope. A super simple example:
For a more advanced example check out the example folder.
What about CSS?
For more advanced CSS animations check out the example folder, specifically
demo.css. This demonstrates some translate/scale animations combined with opacity animations. All the animations are done in CSS so the possibilities are (almost) endless.
|.bind(elements)||Binds new elements to the ScrollTrigger||
|.triggerFor(element)||Returns the Trigger object for the given HTMLElement||
|.destroy(element)||Removes the Trigger object for the given HTMLElement, leaving the DOM untouched, so the classes added by ScrollTrigger will stay put.||
|.destroyAll()||The same as
|.reset(element)||Removes the Trigger object for the given HTMLElement, and removing all traces from ScrollTrigger, so the classes added by ScrollTrigger will be removed.||
|.resetAll()||The same as
|.attach(functionReference)||Attaches a callback to the ScrollTrigger loop, get's called every time the scroll position has changed. Very nice for custom animations.||Check the example below|
|.detach(functionReference)||Removes the callback from the ScrollTrigger loop.||Check the example below|
If you want to add custom animations based on the scroll position, it would be a waste to start another loop / jack the onscroll function. That's why you can attach callbacks to the ScrollTrigger's loop. This is really simple:
Fork, check out
ScrollTrigger.js and enjoy! If you have improvements, start a new branch & create a pull request when you're all done :)
You can see really quickly if the Trigger is working by hitting 'inspect element' in the little menu that pops up when you hit the right mouse button (or ctrl + click if you're one of those oldschool Mac users). Here you can see if the visible/invisble class is toggled when you scroll past the element, is that happening? Then there is something wrong with the CSS.
Found an issue?
Ooh snap, well, bugs happen. Please create a new issue and mention the OS and browser (including version) that the issue is occurring on. If you are really kind, make a minimal, complete and verifiable example and upload that to codepen.
I would love to see how you use ScrollTrigger in your projects! If you are using ScrollTrigger on a live webpage, please hit me up on Twitter @erikterwan, good implementations will be referenced here.
Looking for the old, 1.5kb minified, ScrollTrigger? Check out the legacy branch!