Trigger a callback when two DOM elements overlap
npm install element-overlapTrigger a callback when two DOM elements overlap.
``js
// For ES6:
import listenForOverlap from 'element-overlap';
// ...or for CommonJS:
var listenForOverlap = require('element-overlap').listenForOverlap;
listenForOverlap(
'#element1', '#element2',
function() {
alert('The elements have overlapped!');
}
);
`
The main method to set up a listener for the overlap. Will call callback when the elements areoptions.requiredIntersection
overlapping according to the value .
#### Arguments
##### element1 : < string | HTMLElement >
The first of the two elements to compare. This can either be a
CSS selector string
or a reference to a DOM element (eg: the result of getElementById or querySelector).
##### element2 : < string | HTMLElement >
The second of the two elements to compare. This can either be a
CSS selector string
or a reference to a DOM element (eg: the result of getElementById or querySelector).
##### callback : < function >
The method to be called when the elements have overlapped (according to the value of
options.requiredIntersection).
If options.callbackData is set, this method will be called with options.callbackData provided as
its first argument. For example:
`js`
listenForOverlap(
'#element1', '#element2',
function(callbackData) {
alert('The callback data is: ' + callbackData);
},
{
callbackData: 'Hello, world!'
}
);
Then the browser will alert:
`
The callback data is: Hello, world!"
This is useful if you want to pass some data to your handler functions or you want to give each
listener a unique ID.
##### options : < Object > (optional)
Extra configuration values can be passed in to customise this module from its default behaviour.
Pass an object with any of the following:
###### options.listenOn : < string | Array.
The method/s with which to check for overlaps (and subsequently trigger the callback).
Possible values are:
* 'timer' - Check every n milliseconds (where n is set in options.timerInterval)'scroll'
* - Check whenever user scrolls the browser'resize'
* - Check whenever the browser has been resized
Defaults to 'timer'. If you want to listen on multiple cases, pass in a list like ['scroll', 'resize'].
**PROTIP: for performance-critical code, don't use timer, because it will be doing calculationsn
every milliseconds even if the browser is not moving. Most of the time you want to react to scroll and / or resize.**
###### options.timerInterval : < number >
How often the collision-detection should be checked, in milliseconds. Only used if
options.listenOnis set to 'timer' or [..., 'timer', ...].
**PROTIP: Check less often (ie: use a higher number) if your code is performance-critical, because
then you can avoid doing calculations when not strictly necessary.**
Defaults to 500, ie: check twice every second (or 2 FPS). This should be good enough for most non-'resize'
game applications. Set it even higher if you can in your application. Or even better, use
and / or in options.listenOn instead.
###### options.requiredIntersection : < string >
Determines what is considered a proper 'overlap' and subsequently trigger callback. The options
are:
* 'intersect' - Triggers if any of element1's and element2's pixels are touching.'overlap'
* - Triggers if element1 completely surrounds element2. Note that stacking orderelement1
does not matter here, just that must be bigger than element2.'contain'
* - Triggers if element1 is completely surrounded by element2. Note that stacking element1
order does not matter here, just that must be smaller than element2.
Defaults to 'intersect'.
###### options.callbackData : < any >
Arbitrary data to be passed to callback when it is eventually triggered. For example:
`js`
listenForOverlap(
'#element1', '#element2',
function(callbackData) {
alert('The callback data is: ' + callbackData);
},
{
callbackData: 'Hello, world!'
}
);
Then the browser will alert:
`
The callback data is: Hello, world!"
This is useful if you want to pass some data to your handler functions or you want to give each
listener a unique ID.