jQuery Nearest Element plugin

Quick Links

(Be kind to Github, don't hotlink JS files)

Intro

This plugin finds the elements in a page that are closest to a particular point or element, based on pixel dimensions. This is not to be confused with jQuery's own .closest() method, which is based on the DOM tree, not pixels.

There are also helper methods to find elements that are the furthest away from or touching a point or element.

Reference

Methods

There are three main methods:

.nearest() returns the elements that have the shortest pixel distance to a point or element.
.furthest() returns the elements that have the longest pixel distance to a point or element.
.touching() returns the elements that are touching a point or element (ie. their pixel distance is 0).

Usage

Each of the three methods has a utility function on the global jQuery object and a jQuery prototype function for working with element sets. The following examples all use nearest as the method, but furthest and touching work in the same way.

Utility Function

$.nearest(pointObject, selector[, options]);

Finds the DOM elements matching selector that are closest to a point or region on the page.

pointObject is an object with x and y (numeric) properties that define a point on the page (relative to the top left corner of the page, not the screen).
Optionally, you can also specify w and h properties to define the width and height respectively of a region in the page instead of a single point – in this case the x and y properties define the top left corner of the region.

The x, y, w and h properties can also be defined as a percentage string, relative to the container option (defined in the options section).

selector is any valid jQuery selector or object that defines an element set to be filtered by the function.

options is an optional collection of parameters to pass to the function. More details can be found in the options section.

Example

// Find the image(s) closest to a point 300px in and 100px down from the top left corner
var $closestToPoint = $.nearest({x: 300, y: 100}, 'img');

// Find the elements with class 'floating' closest to a particular region in the page
var $elemSet = $('.floating');
var $closestToRegion = $.nearest({x: 300, y: 100, w: 200, h: 200}, $elemSet);

// Find the elements with class 'floating' closest to the right-hand side of the document
var $closestToRightEdge = $.nearest({x: '100%', y: 0, h: '100%'}, '.floating');

Single Element Operation

$(elem).nearest(selector[, options]);

Finds the DOM elements matching selector that are closest to elem. If more than one element is in $(elem) then only the first member will be used as a point of reference.

selector is any valid jQuery selector or object that defines an element set to be filtered by the function.

options is an optional collection of parameters to pass to the function. More details can be found in the options section.

Example

var $basicExample = $('#something').nearest('.surrounding');

// Only the first element in this set will be used for matching
var $set = $('.middle');
// Selector can be any jQuery object
var $convolutedExample = $set.nearest($set.siblings());

Multiple Element Filter

$(elemSet).nearest(pointObject[, options]);

Filters elemSet to return only the members that are closest to the point or region defined by pointObject.

This is effectively the same as calling $.nearest(pointObject, elemSet) but with the benefit of not breaking method chains – see chaining for more details.

pointObject is an object as defined in the Utility Function reference.

options is an optional collection of parameters to pass to the function. More details can be found in the options section.

Example

var $set = $('.filterme');

// Filter the set by distance to a point
var $closestToPoint = $set.nearest({x: 300, y: 100});

// Filter the set by distance to a region
var $closestToRegion = $set.nearest({x: 300, y: 100, w: 200, h: 200});

Options

All methods take an optional options object to further refine the results. The object can have the following parameters:

includeSelf: Boolean - default false (not used by the utility methods); If true, the reference element used in a Single Element Operation will also be included in the distance calculations.
Example: $(elem).nearest('.droppable', {includeSelf: true});
checkHoriz: Boolean - default true (not used by .touching()); If false, the function will not check for elements along the X axis, meaning only elements directly above or below the reference point will be matched.
checkVert: Boolean - default true (not used by .touching()); If false, the function will not check for elements along the Y axis, meaning only elements directly to the left or right of the reference point will be matched.
tolerance: Integer - default 1; Number of pixels to allow for when calculating distances, to account for fractional pixel values.
For example, a tolerance of 1 would match distances of 23px, 23.45px and 24px as being closest, but not 24.1px.
container: DOM node or jQuery selector - default document (not used by .touching()); Used with percentage options for x, y, w and h.
Defines the container to measure percentage values against. The top left corner of the container is 0%, the bottom right corner is 100%.

A example of using different options can be found on the demonstration page.

Notes

The selector parameter is technically optional in all methods, and will default to div if not present. However, it is strongly recommended that you pass in a selector, otherwise the method will loop through every single div element on the page, which – apart from being slow and computationally expensive – will most likely produce false positives by matching a reference element's parent nodes.
Only set one of the checkHoriz and checkVert options to false in a single call, not both. If you set both to false, the .nearest() and .furthest() methods will fail to work (it is technically the same as calling .touching() instead).