The Hitbox object

Hitbox constructor

The detection of the collisions begins by creating an object that will watch the DOM.

const hitboxWatcher = new Hitbox(options)

options is an object with several arguments.

Constructor arguments (in the {options} object)

elements

Expected type	Required
string | NodeList | Node	Yes

The CSS selector or a NodeList of the elements you want to watch. Any collision between any of those elements will trigger a collision event.

If you need to later add elements that will be taken in account for collisions detection, the type of this argument matter. See Static vs dynamic targets.

With CSS Selector

const hitboxWatcher = new Hitbox({
    elements: '.my-elements'
})

With NodeList

const myElements = document.querySelectorAll('.my-elements')

const hitboxWatcher = new Hitbox({
    elements: myElements
})

With single element

const myElement = document.querySelector('#my-element')

const hitboxWatcher = new Hitbox({
    elements: myElement
})

targetElements

Expected type	Required
string | NodeList | Node	No

The CSS selector or a NodeList of a second set of elements you want to watch.

If provided, collision events will only fire when an element from elements hits an element from targetElements.

If you need to later add elements that will be taken in account for collisions detection, the type of this argument matter. See Static vs dynamic targets.

Example

const hitboxWatcher = new Hitbox({
    elements: '.my-elements',
    targetElements: '.my-target-elements'
})

watch

Expected type	Required	Default value
boolean	No	true

Determines if the watcher should start watching immediately. Default to true but if set to false, the watcher can be activated later with the .watch() method

Example

const hitboxWatcher = new Hitbox({
    elements: '.my-elements',
    watch: false
})

debug

Expected type	Required	Default value
boolean	No	false

Enables debugging mode if set to true.

Example

const hitboxWatcher = new Hitbox({
    elements: '.my-elements',
    debug: true
})

minOverlap

Expected type	Required	Default value
numberbetween 0 and 1	No	0

Defines the minimum overlap collision value required to fire an event. See the dedicated page.

Conditional detection

onScreenOnly

Expected type	Required	Default value
boolean	No	false

This future feature is still in development and is not available in the released builds on NPM or via CDN.

If set to true, the collision events will only be triggered by elements that are visible on the screen. If an element is outside of the viewport, it will not be taken in account.

Example

const hitboxWatcher = new Hitbox({
    elements: '.my-elements',
    onScreenOnly: true
})

Methods

.on(event, callback)

Argument	Type	Required
event	string	Yes
callback	Function	Yes

Registers a function to be called when an event happens.

The callbackfunction will be called whenever there is a collision, with a Collision object as argument.

Possible values for event

There are 3 event types that you can register callbacks for:

• collision: called while the elements are colliding

• collisionStartcalled when the elements start colliding

• collisionEnd: called just after the elements stopped colliding

collision

hitboxWatcher.on('collision', function (collision) {
    // Do something with the collision object
})

collisionStart

hitboxWatcher.on('collisionStart', function (collision) {
    // Do something with the collision object
})

collisionEnd

hitboxWatcher.on('collisionEnd', function (collision) {
    // Do something with the collision object
})

.onCollision(callback)

Argument	Type	Required
callback	Function	Yes

Alias function for .on('collision', callback).

.onCollisionStart(callback)

Argument	Type	Required
callback	Function	Yes

Alias function for .on('collisionStart', callback).

.onCollisionEnd(callback)

Argument	Type	Required
callback	Function	Yes

Alias function for .on('collisionEnd', callback).

.watch()

Enables the watcher if it was not already watching.

const hitboxWatcher = new Hitbox({
    elements: '.my-elements',
    watch: false
})
// Hitbox is not watching for collisions

hitboxWatcher.watch()

// Now, Hitbox is watching for collisions

.unwatch()

Disables the watcher.

const hitboxWatcher = new Hitbox({
    elements: '.my-elements'
})
// Hitbox is watching for collisions

hitboxWatcher.unwatch()

// Hitbox is not watching for collisions anymore

.setDebug(set)

Argument	Type	Required
set	boolean	Yes

Enables or disables the debugging mode according to the set boolean value.

const hitboxWatcher = new Hitbox({
    elements: '.my-elements'
})

hitboxWatcher.setDebug(true) // Debug mode is now enabled

hitboxWatcher.setDebug(false) // Debug mode is now disabled