ScrollAnim is a widget that animates HTML elements based on vertical page scroll. With ScrollAnim widget, you can quickly create sites that have various HTML elements move or fade according to how far the user has scrolled down the site. The animation for each HTML element is also gracefully controlled by easing functions of your choosing. Also the widget is great for achieving the popular "parallax effects", when certain elements (especially the backgrounds) move at a different speed than the user-controlled scrolling speed.
To include the source files for ScrollAnim and its dependencies, first load the YUI seed file if you haven't already loaded it.
``` ```Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the `YUI().use()` method. YUI will automatically load any dependencies required by the modules you specify.
``` ```For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.
The following code example shows the basic widget configuration and how instantiate the ScrollAnim widget. The widget will be up and running after it is successfully instantiated.
``` /* Somewhere inside YUI().use() callback function */ var scrollAnimConfig = { node: '#scrollanim-container', // main container selector animations: animations, // animation data (IMPORTANT) maxScroll: 1500 // max scroll }, scrollAnimWidget; /* Scroll animation will start immediately after instantiation */ scrollAnimWidget = new Y.ScrollAnim(scrollAnimConfig); ```The most important data to the widget is the `animation` attribute. Please see the following section for more information on the structure and required properties in the `animation` attribute.
ScrollAnim requires the following attributes to be set, in addition to the attributes provided by the base Widget class:
| Attribute (Required) | Description |
|---|---|
| `node` | Main container selector |
| `animations` | Animation data for all animated HTML elements |
| `maxScroll` | Maximum `window.scrollTop` value in which the scrolling animation should stop |
The following are optional attributes:
| Attribute (Optional) | Description | Default Value |
|---|---|---|
| `startAt` | Minimum `window.scrollTop` value in which the scrolling animation should start | 0 (pixel) |
| `useRAF` | Set if the widget should use `window.requestAnimationFrame` method when available. | true |
| `tickSpeed` | Set interval (ms) for `window.setInterval` if not using RAF | 100 (milliseconds) |
| `scrollSpeed` | Scrolling animation speed, controlling how responsive the animation is to user mouse wheel scroll, from 0-100 | 20 |
| `tweenSpeed` | `window.scrollTop` tween speed | 0.3 |
| `debug` | Turn on debug mode | false |
| `onStart` | Custom function called once when the widget starts the animation | Null |
| `onUpdate` | Custom function called every time an animation frame is rendered | Null |
| `onResize` | Custom function called when the window is resized | Null |
The `animation` attribute will contain individual animation details for each HTML element. Below is an example of the animation attribute:
``` var animation = [ { selector: '#divContainer', startAt: 500, endAt: 1200, onEndAnimate: function( anim ) {}, keyframes: [ { position: 0, properties: { "top": 0, "background-position" : {x:"50%",y:0} } }, { position: 1, ease: TWEEN.Easing.Linear.EaseNone, properties: { "top": 100, "background-position" : {x:"50%",y:-100} } } ] }, { selector: '#divContainer article', startAt: 0, endAt: 600, onEndAnimate: function( anim ) {}, keyframes: [ { position: 0, properties: { "top": 250, "opacity": 1 } }, { position: 1, ease: TWEEN.Easing.Quadratic.EaseInOut, properties: { "top": -100, "opacity": 0 } } ] } ] ```The following table shows all possible properties to each object in the animation attribute:
| Property | Description | Type | Required |
|---|---|---|---|
| `selector` | CSS selector used to retrieve an element | String | Yes |
| `startAt` | `window.scrollTop` position where the animation for this element should start | Integer | Yes |
| `endAt` | `window.scrollTop` position where the animation for this element should end | Integer | Yes |
| `keyframes` | ScrollAnim widget uses this to determine which CSS properties to update at each time interval or request animation frame and what are the values for the CSS properties at the start and end of the animation. Please see the next table about the `keyframe` array on exactly what should be included. | Array | Yes |
| `onInit` | Custom function called only once at the start of the element's animation | Function | No |
| `onStartAnimate` | Custom function to call at each animation frame | Function | No |
| `onEndAnimate` | Custom function to call at the end of the element's animation | Function | No |
The following table shows what properties should be included in the objects in the `keyframe` array:
| Property | Description |
|---|---|
| `position` | Either 0 or 1. 0 indicates this is the keyframe at the start of the animation. 1 indicates this is the keyframe at the end of the animation. |
| `properties` | An object containing all the CSS properties whose values need to be updated when the element is animated. |
| `ease` | The easing function used to animate the element. This property only need to be included in the end position object. Please see 3rd Party Dependency section below for more information on how to specify the easing function to use. |
| `onInit` | Custom function invoked at the beginning of the element's animation. Should only be included in the position "0" object. |
The widget does not require much markup beyond the widget container. However, for most cases you will have a site that needs the users to scroll vertically. In this case, you will need a parent element containing the rest of the animated elements that will move upward. To achieve this you will need specific markup, CSS, and configuration in the `animation` attribute. You can also see a working example of a long scrolling animation site from the examples page.
The markup needed:
```The configuration needed:
``` var animations = [ { selector: '#verticalScrollArea', startAt: 0, /* Vertical scroll element should animate at the very top */ endAt: 1500, /* End animation at the same position as the "maxScroll" attribute */ keyframes: [ { position: 0, /* Start keyframe */ properties: { top: 0 /* Set "top" to 0 at the beginning of the animation */ } }, { position: 1, /* End keyframe */ ease: TWEEN.Easing.Linear.EaseInOut, /* Easing effects on vertical scroll container if needed */ properties: { top: -1000 /* Set "top" to how much the vertical container should scorll in the end */ } } ] }, /* ... animation objects for children elements */ ] ```CSS needed:
``` body { /* Browser does not render the correct scroll progress in the default scrollbar when we're simply adjusting a container element's "top" property to simulate vertical scrolling. */ overflow: hidden; } #verticalScrollArea{ /* This is important so this element can be moved vertically by the widget to create vertical scrolling page. */ position: absolute; } ```Except as specifically stated here, the 3rd party software packages are not distributed as part of this project, but instead are separately downloaded from the respective provider and built on the developer’s machine as a pre-build step.