inview-detection
v1.0.10TypeScript
0/weekUpdated 1 years agoISCUnpacked: 146.9 KB
Published by @coderesolution
npm install inview-detectionInview Detection
Inview Detection enables the creation of sequential animations based on in-view detection using custom data-inview-* attributes in the DOM. Powered by GSAP.
Features
- Standalone elements
- Scoping, bind elements to parent
- Custom queuing and animations
- Trigger callbacks
- Conditional classes
- Repeatable
- Target specific screen sizes
- Debugging mode
- Lightweight (1.63 kB gzipped)
Dependencies
Ensure the following dependencies are installed and properly registered:
Quick start
Inview Detection requires the GSAP library as well as ScrollTrigger to function correctly. Ensure both are included before Inview Detection and registered within the instantiation.
$3
``js
import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import InviewDetection from 'inview-detection'
// Register ScrollTrigger plugin
gsap.registerPlugin(ScrollTrigger)
// Initialise InviewDetection and pass in gsap and ScrollTrigger
const inview = new InviewDetection(
{
/ options /
},
gsap,
ScrollTrigger,
)
`
$3
To initialise the module without starting it immediately, set autoStart option to false.
`js
// Create instance but do not start automatically
const inview = new InviewDetection(
{
autoStart: false,
},
gsap,
ScrollTrigger,
)
// Start it when you are ready
document.addEventListener('DOMContentLoaded', () => {
inview.start()
})
`
With autoStart disabled, for extra clarity inview.register can be used to register gsap and ScrollTrigger outside of the instantiation.
`js`
// Standard
const inview = new InviewDetection(
{
autoStart: false,
},
gsap,
ScrollTrigger,
)
Optionally may be replaced with:
`js
const inview = new InviewDetection({
autoStart: false,
})
// Register gsap and ScrollTrigger separately
inview.register(gsap, ScrollTrigger)
`
$3
If you prefer to use a CDN, here is an example:
`html
`
Options
You can configure Inview Detection via options:
`js`
const inview = new InviewDetection(
{
elements: '[data-inview]',
autoStart: true,
screen: '(min-width: 1025px)',
duration: 1,
delay: 0.1,
start: 'top 90%',
ease: 'power4',
stagger: 0.08,
animationFrom: {
opacity: 0,
'will-change': 'transform',
y: 20,
},
animationTo: {
opacity: 1,
y: 0,
},
inviewClass: 'is-inview',
viewedClass: 'has-viewed',
debug: false,
},
gsap,
ScrollTrigger,
)
All options:
| Name | Type | Default | Description |
| :-------------- | :----: | :-----------------------: | :----------------------------------------------------------------------------------------------------------------------------------- |
| elements | str | [data-inview] | What elements to apply inview animations to. |autoStart
| | bool | true | Whether to start immediately. 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. |duration
| | num | 1 | Duration of each animation. |delay
| | num | .1 | Delay before animation starts. |start
| | str | top 90% | ScrollTrigger's starting position for the animation. |ease
| | str | power4 | Easing of animation (help). |stagger
| | num | 0.08 | Time between each animation in the sequence. |animationFrom
| | json | {"opacity": 0, "y": 20} | The initial state of each animation. |animationTo
| | json | {"opacity": 1, "y": 0} | The final state of each animation. |inviewClass
| | str | 'is-inview' | The class that is temporarily assigned to elements when they are within the viewport. |viewedClass
| | str | 'has-viewed' | The class that is permanently assigned to elements 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-inview] to enable custom animations.
- scope
- child
- debug
- order
- repeat
- from/to
- start
- end
- screen
- call
$3
Attribute: data-inview-scope
Type:
Specify the scope of nested elements using wildcards like , > or selectors .class, #id.
`html`
$3
Attribute: data-inview-child
Apply attribute to elements that should animate when parent comes into view. The parent must have [data-inview] and [data-inview-scope] attributes.
`html`
Child 1
Child 2
$3
Attribute: data-inview-debug
Enable debugging markers and logs for animations.
`html`
$3
Attribute: data-inview-order
Type:
Specify the order of animation for elements within a scope.
`html`
First
Second
$3
Attribute: data-inview-repeat
Allow animations to re-trigger when elements re-enter the viewport.
`html`
$3
Attributes: data-inview-from, data-inview-to
Type:
Specify custom gsap.from() and gsap.to() properties for animations.
`html`
Custom Animation
$3
Attribute: data-inview-start
Default: or 'top top' if (sticky)[#sticky] is setstr
Type:
Adjust the point when the animation begins.
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:
Default: or bottom bottom if (sticky)[#sticky] is set
Type: strAdjust 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:
Default: (configurable globally via options)
Type: strSet screen size conditions for the animation. For example: animate on desktop and not mobile, or vice-versa. Expects media queries like
or (min-width: 768px) and (max-width: 1000px) etc. Set to all to animate on all screen sizes.$3
Attribute:
data-inview-call
Default: Not set
Type: Fire custom JavaScript events when elements enter and leave the viewport.
Data such as
, direction (up/down) and when (enter, re-enter, leave and leave-again) are accessible within an event listener.`html
Trigger
`js
window.addEventListener('inviewEvent', (e) => {
const { target, direction, when } = e.detail
console.log(target: ${target}, direction: ${direction}, when: ${when})
})
`Methods
$3
Start Inview Detection to initialise animations, useful when
is set to false.`js
inview.start()
`$3
Register
and ScrollTrigger dependencies with InviewDetection.`js
inview.register(gsap, ScrollTrigger)
`$3
Update ScrollTrigger calculations, useful if the page height changes.
js
inview.refresh()
`$3
Stop all animations and remove the ScrollTrigger instances.
js
/ Stop all animations /
inview.stop()/ Stop a specific animation /
const element = document.querySelector('#myElement')
const trigger = inview.fetch(element)
inview.stop(trigger)
`$3
Stop and restart animations.
js
inview.restart()
`Classes
| Class | Application |
| :----------- | :----------------------------------------------------------- |
|
| Temporarily assigned to elements when they are in view. |
| has-viewed | Permanently assigned to element when they have been in view. |Events
$3
Detect when elements enter or leave the viewport.
`js
inview.on('onEnter', (element) => {
console.log('Entering view:', element)
})
inview.on('onLeave', (element) => {
console.log('Leaving view:', element)
})
inview.on('onEnterBack', (element) => {
console.log('Re-entering view:', element)
})
inview.on('onLeaveBack', (element) => {
console.log('Leaving view again:', element)
})
`$3
Detect when the
method is fired.`js
inview.on('refresh', () => {
console.log('Refreshed')
})
`$3
Detect when the
method is fired.`js
inview.on('stop', (target) => {
console.log('Stopped', target)
})
`$3
Detect when the
method is fired.`js
inview.on('restart', () => {
console.log('Restarted')
})
``Examples of use
- Code Resolution
- Bay Harbor Towers
- PAL Aerospace
- Enumera Molecular
- ONE38
- Stairwell
- Divino
- US Foot & Ankle Specialists