Perimeter.js

Creates an invisible perimeter around a target element and monitors mouse breaches.

More info, documentation and examples @ http://github.e-sites.nl/perimeter.js/

Use cases

Get the user's attention, in terms of showing some sort of tooltip / popover when hovering near a certain element, like a hint or a tip.
Lazy load a script when the perimeter of the target element is breached (AFAIK Google does this when a user moves it's mouse towards the red 'compose' button).
Fetch data via AJAX and do something with it when a users navigates towards a certain element.

Specs

Lightweight; (~0.6kb minified / gzipped)
No dependencies; just plug it in and you're good to go
Built-in debugger to actually see where the perimeter is located (boundary.js)
Fully documented
Unit-tests available

Getting started

First and foremost, download the script and include it as follows:

<script src="perimeter.min.js"></script>

Second, just call the Perimeter constructor function and pass the corresponding options.

new Perimeter({
    target: 'square',
    outline: 20,
    onBreach: function () {
        // Breach!
    }
});

UPDATE: as from 0.2.0 is also possible to pass DOM elements as target (instead of only a string). This way you can instantiate multiple Perimeters within a loop:

var items = document.querySelectorAll('.selector'),
    i = items.length;

while (i--) {
   Perimeter({
       target: items[i],
       outline: 100
   });
}

In case you're working with perimeter.debug.js you'll need to add a bit of CSS to actually see the boundary:

.boundary {
    position:absolute;
    border:1px dotted;
    background:#E4FECB;
    background:rgba(127,255,0,0.2);
    margin:0;
    padding:0;
    z-index:-1;
}

Options

Property	Type	Description
`target`	`{String\|HTMLElement}`	Either a string with the ID of the target element or a DOM element. If the corresponding element is not present the script will fail silently.
`monitor`	`{HTMLElement}`	Element where the `mousemove` event will be bound to and therefore acts as monitor for breaches.
`outline`	`{Number\|Array}`	Outline around the target element. This can either be an array with top/right/bottom/left dimensions or just one number which acts as shorthand for all directions.
`debug`	`{Boolean}`	When debugging in a local environment you can pass the `debug` option. This will create a division that will be positioned absolutely to the `body` and basically shows where the perimeter is located. By default, the debug functionality is excluded from `perimeter.js`. So, please make sure that you include `perimeter.debug.js`.
`onBreach`	`{Function}`	Callback function that will be invoked when the monitor detects a breach.
`onLeave`	`{Function}`	Callback function that will be invoked when the mouse cursor leaves the perimeter.

Browser support

Tested in the latest (stable) versions of Google Chrome, Mozilla Firefox, Opera and Safari. As for Internet Explorer; I have tested in IE8+ but it should work in IE7 as well (though, it might be quirky).

Note: needless to say, since Perimeter.js listens to the mousemove event to detect breaches it will not work on mobile devices.

Road map

When I have some spare time I will try to accomplish the following:

Performance measurements
More documentation / examples
Unit testing

e-sites/perimeter.js

e-sites

Reviews

Repository Details