inview-detection
v1.0.7
Published
Inview Detection enables the creation of sequential animations based on in-view detection. Powered by GSAP.
Downloads
311
Readme
Inview Detection
Inview Detection enables the creation of sequential animations based on in-view detection. 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.
Install from NPM
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,
)
Delayed start (recommended)
To initialise the module without starting it immediately, set autoStart
option to false
.
// 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.
// Standard
const inview = new InviewDetection(
{
autoStart: false,
},
gsap,
ScrollTrigger,
)
Optionally may be replaced with:
const inview = new InviewDetection({
autoStart: false,
})
// Register gsap and ScrollTrigger separately
inview.register(gsap, ScrollTrigger)
Install from CDN
If you prefer to use a CDN, here is an example:
<!-- Include GSAP -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.11.5/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.11.5/ScrollTrigger.min.js"></script>
<!-- Include InviewDetection -->
<script src="https://cdn.jsdelivr.net/npm/inview-detection/bundled/index.min.js"></script>
<script>
// Register ScrollTrigger plugin
gsap.registerPlugin(ScrollTrigger)
// Initialise InviewDetection and pass in gsap and ScrollTrigger
const inview = new InviewDetection(
{
/* options */
},
gsap,
ScrollTrigger,
)
</script>
Options
You can configure Inview Detection via options:
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
for scoped elements within parentchild
for child elements that should animate with parentdebug
for enabling debugging markers and logsorder
for specifying the order of animationrepeat
for allowing repeat animationsfrom
for setting animation from propertiesto
for setting animation to properties
Scope
Attribute: data-inview-scope
Type: string
Specify the scope of nested elements using wildcards like *
, > *
or selectors .class, #id
.
<div data-inview data-inview-scope="> *">
<!-- All direct children will be considered for animation -->
</div>
Child
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.
<div data-inview data-inview-scope>
<div data-inview-child>Child 1</div>
<div data-inview-child>Child 2</div>
</div>
Debug
Attribute: data-inview-debug
Enable debugging markers and logs for animations.
<div data-inview data-inview-debug></div>
Order
Attribute: data-inview-order
Type: number
Specify the order of animation for elements within a scope.
<div data-inview>
<div data-inview-child data-inview-order="1">First</div>
<div data-inview-child data-inview-order="2">Second</div>
</div>
Repeat
Attribute: data-inview-repeat
Allow animations to re-trigger when elements re-enter the viewport.
<div data-inview data-inview-repeat></div>
From / To
Attributes: data-inview-from
, data-inview-to
Type: json
Specify custom gsap.from()
and gsap.to()
properties for animations.
<div data-inview data-inview-from='{"opacity": 0, "y": 20}' data-inview-to='{"opacity": 1, "y": 0}'>
Custom Animation
</div>
Methods
Start
Start Inview Detection to initialise animations, useful when autoStart
is set to false
.
inview.start()
Register GSAP
Register gsap
and ScrollTrigger
dependencies with InviewDetection.
inview.register(gsap, ScrollTrigger)
Refresh
Update ScrollTrigger calculations, useful if the page height changes.
inview.refresh()
Stop and fetch
Stop all animations and remove the ScrollTrigger instances.
/* Stop all animations */
inview.stop()
/* Stop a specific animation */
const element = document.querySelector('#myElement')
const trigger = inview.fetch(element)
inview.stop(trigger)
Restart
Stop and restart animations.
inview.restart()
Classes
| Class | Application |
| :----------- | :----------------------------------------------------------- |
| is-inview
| Temporarily assigned to elements when they are in view. |
| has-viewed
| Permanently assigned to element when they have been in view. |
Events
Enter/Leave the viewport
Detect when elements enter or leave the viewport.
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)
})
Refresh
Detect when the inview.refresh()
method is fired.
inview.on('refresh', () => {
console.log('Refreshed')
})
Stop
Detect when the inview.stop()
method is fired.
inview.on('stop', (target) => {
console.log('Stopped', target)
})
Restart
Detect when the inview.restart()
method is fired.
inview.on('restart', () => {
console.log('Restarted')
})