Available on npm (npm install jquery-nearest)
and Bower (bower install jquery-nearest).
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.
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).
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.
$.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.
// 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');
$(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.
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());
$(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.
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});
All methods take an optional options object to further refine the results.
The object can have the following parameters:
includeSelffalse (not used by the utility methods)$(elem).nearest('.droppable', {includeSelf: true});onlyXfalse (not used by .touching())onlyYfalse (not used by .touching())sameXfalse (not used by .touching())onlyX: true if both are provided.sameYfalse (not used by .touching())onlyY: true if both are provided.tolerance1containerdocumentx, y, w and h – the top left corner of the container is 0%, the bottom right corner is 100%.directionConstraintsempty"left", "right", "top", "bottom"["left", "top"] will only match elements to the top left of the reference point.sortempty"nearest" or "furthest"checkHoriztrue – Deprecated in 1.3checkHoriz: false option is deprecated and will be removed in a future version. Use sameX: true instead (they are equivalent).checkVerttrue – Deprecated in 1.3checkVert: false option is deprecated and will be removed in a future version. Use sameY: true instead (they are equivalent).A example of using different options can be found on the demonstration page.
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.
sameX and sameY options to true in a single call, not both.
If you set both to true, the .nearest() and .furthest() methods will fail to work (it is exactly the same as calling .touching() instead).
container element if the option is present.
(PR #5).tolerance option to account for fractional pixel values and “close enough” situations
(#1).