Onscroll Detection enables the creation of powerful GSAP animations using custom `data-onscroll-*` attributes in the DOM. It leverages GSAP and ScrollTrigger to easily create scroll-based parallax animations, custom transforms, progressive animations, and
Onscroll Detection enables the creation of powerful GSAP animations using custom data-onscroll-* attributes in the DOM. It leverages GSAP and ScrollTrigger to easily create scroll-based parallax animations, custom transforms, progressive animations, and more.
- Bind animations to any trigger element. - Manipulate classes based on scroll events. - Trigger callbacks on specific events. - Supports both vertical and horizontal directions with the ability to reverse. - Control animation through specific px values, from and to attributes, modify scroll speed, or automatically calculate distance based on parent. - Create custom animations such as rotation, skewing, colour changes, and more. - Target specific screen sizes for adaptive animations. - Built-in debugging mode. - Lightweight (~2.71 kB Brotli).
Dependencies
Please ensure the following dependencies are installed and properly registered:
Onscroll Detection requires GSAP and ScrollTrigger plugin to work. Both must be included before Onscroll Detection and registered within the instantiation.
#### Install from NPM
``js import { gsap } from 'gsap' import { ScrollTrigger } from 'gsap/ScrollTrigger' import OnscrollDetection from 'onscroll-detection'
| Name | Type | Default | Description | | :--------------- | :----: | :---------------------: | :----------------------------------------------------------------------------------------------------------------------------------- | | elements | str | [data-onscroll] | What elements to apply onscroll animations to. | | autoStart | bool | true | Whether to start immedietely. Set to false for a delayed start (recommended). | | screen | str | '(min-width: 1025px)' | Specify media query rules for animations. This can be overwritten on a per animation-basis. Set to all to remove queries entirely. | | startPosition | str | 'top bottom' | Global default start position for all animations. Can be overridden per element using data-onscroll-start. | | endPosition | str | 'bottom top' | Global default end position for all animations. Can be overridden per element using data-onscroll-end. | | scrollingClass | str | 'is-scrolling' | The class that is temporarily assigned to elements when they are within the viewport. | | scrolledClass | str | 'has-scrolled' | The class that is permanently assigned to element when they have been within viewport. | | stickyClass | str | 'has-sticky' | The class that is temporarily assigned to sticky element set by [data-onscroll-sticky] when they are within the viewport. | | stuckClass | str | 'has-stuck' | The class that is permanently assigned to sticky element set by [data-onscroll-sticky] when they have been within the viewport. | | debug | bool | false | Set debug mode to all instances. Enables markers and console logs. |
Attributes
Apply any of the following data attributes in conjunction with [data-onscroll] to enable custom animations.
Apply before and after offsets. This settings expects two comma-separated multipurpose values, like 100,-100. The first value applies an initial offset at the beginning of the animation. The second value is the target offset.
###### px values or percentages
Integers default to px values, inclusion of % will set as a percentage value. Percentage values are based on the element height.
###### Recommended: Preset
Combine with data-onscroll-preset (see preset) to automatically update the start (see start) and end (see end values for seamless offset animations.
###### Sticky elements
If data-inview-sticky (see sticky) is set, the first value adds top padding for a late stick and the second value adds a bottom padding for an earlier unstick.
`html
`
$3
Attribute:
data-onscroll-delay Default: 0 Type: int (number)
Apply a lag/lerp effect to delay an element's response to the user's scrolling. The value represents the duration (in seconds) of the animation (e.g.,
2 for two seconds).
Note: To be used only in conjunction with offset animations, however, distances may not be completely accurate when a delay is used.
`html
`
_offset in the above example is for illustrative purposes_
$3
Attribute:
data-onscroll-preset Default: false Type: Toggle (no value)
Automatically adjust
start and end values based on offset settings to eliminate the need for complex values like data-onscroll-start="top bottom+=200" (see start and end ).
Note: If the offset value exceeds
0, the start will be where the original element was before offset is applied. This avoids a jump as it comes into view.
Only to be used with
data-onscroll-offset (see offset. This has no effect on speed (see speed) as that is calculated independently.`html
`
_offset in the above example is for illustrative purposes_
$3
Attribute:
data-onscroll-auto Default: Not set Type: Toggle (no value)
Achieve a parallax effect by automatically applying offset/distance if an element exceeds the height of the parent container or defined trigger (see trigger.
This is best used for creating parallax effects to contained images or backgrounds.
`html
`
_reverse in the above example is for illustrative purposes_
$3
Attribute:
data-onscroll-reverse Default: Not set Type: Toggle (no value)
This has no effect on the offset or speed setting.
`html
`
$3
Attribute:
data-onscroll-speed Default: Not set Type: x2 comma separated values (int,int)
Instead of using precise pixel or percentage values with an offset animation, use a speed effect. This setting requires two comma-separated values, such as
1.5,10. The offset animation is applied by multiplying the height of the element (first value) and adding the percentage value of the viewport height (second value). For instance, 1.5,10 represents (1.5 times the element height) plus (10% of the viewport height). Therefore, data-onscroll-speed="1,0" is equivalent to data-onscroll-offset="0,100%". Negative values are also accepted to reverse the direction.`html
`
$3
Attribute:
data-onscroll-direction Default: 'y' Type: string
Change direction of the animation.
Only the following values will be accepted: | Direction | Value | Description | | :--------: | :---: | :----------------------------------------------------------------------------------------: | | Vertical |
y | Defaults to down unless using reverse attribute or negative offset and speed values. | | Horizontal | x | Defaults to right unless using reverse attribute or negative offset and speed values. | | Both | xy | Defaults to down/right unless using reverse attribute or negative offset and speed values. |`html
`
_offset in the above example is for illustrative purposes_
$3
Attribute:
data-onscroll-trigger Default: this Type: string (DOM element by selectors, i.e. #id, .class)
Set an alternative element as the trigger instead of itself. Specificity is crucial to ensure only a single element is assigned.
`html
`
When using the Code Resolution boilerplate for WordPress, you can set the component as the target like so:
`php echo ""; `
$3
Attribute:
data-onscroll-sticky Default: Not set Type: Toggle (no value)
Stick element to the
data-onscroll-trigger element.
Combine with
data-onscroll-offset (see offset) for early and late stick/unstick. The first value (top) adjusts the initial stick and the second value (bottom) adjusts unstick.`html
`
_offset in the above example is for illustrative purposes_
$3
Attribute:
data-onscroll-start Default: 'top bottom' or 'top top' if sticky is set Type: str
Adjust the point when the animation begins. See preset for automatic detection with offsets.
The first value refers to the trigger and the second value refers to the viewport. Refer GSAP ScrollTrigger documentation for further information.
`html
`
$3
Attribute:
data-onscroll-end Default: 'bottom top' or bottom bottom if sticky is set Type: str
Adjust the point when the animation ends. See preset for automatic detection with offsets.
The first value refers to the trigger and the second value refers to the viewport. Refer GSAP ScrollTrigger documentation for further information.
`html
`
$3
Attribute:
data-onscroll-screen Default: '(min-width: 1025px)' (configurable globally via options) Type: str`