jQuery Nearest Element plugin v1.4.0

Quick Links

Available on npm (npm install jquery-nearest) and Bower (bower install jquery-nearest).

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:

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});
onlyX
Boolean – default false (not used by .touching())
If true, the function will ignore the Y axis and only the X distance from the reference point will be used.
onlyY
Boolean – default false (not used by .touching())
If true, the function will ignore the X axis and only the Y distance from the reference point will be used.
sameX
Boolean – default false (not used by .touching())
If true, the function will not check for elements along the X axis, meaning only elements directly above or below the reference point will be matched.
This will override onlyX: true if both are provided.
sameY
Boolean – default false (not used by .touching())
If true, 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.
This will override onlyY: true if both are provided.
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
Acts as a root node, so that only elements within the container will be matched.
Also used with percentage options for x, y, w and h – the top left corner of the container is 0%, the bottom right corner is 100%.
directionConstraints
String array – default empty
A list of directions to limit the search. Available values: "left", "right", "top", "bottom"
For example, ["left", "top"] will only match elements to the top left of the reference point.
sort
String – default empty
Sorts results based on distance, defaults to no sorting (results are returned in DOM order).
Available values: "nearest" or "furthest"
checkHoriz
Boolean – default trueDeprecated in 1.3
The checkHoriz: false option is deprecated and will be removed in a future version. Use sameX: true instead (they are equivalent).
checkVert
Boolean – default trueDeprecated in 1.3
The checkVert: 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.

Notes

Changelog

1.4.0
  • New directionConstraints option (PR #29).
  • New sort option (PR #29).
1.3.1
  • No code changes. Metadata updates only (#15, #16, #25).
1.3.0
  • New onlyX and onlyY options (PR #7).
  • New sameX and sameY options as the inverse replacement for checkHoriz and checkVert (#9).
  • Deprecated the checkHoriz and checkVert options.
  • Bug fix for filtering on empty sets.
  • Better calculation of dimensions for percentage-based options.
1.2.2
  • Bug fix to find only children of the container element if the option is present. (PR #5).
1.2.1
1.2.0
  • Added to Bower (#4).
  • New container option and the ability to use percentage-based strings for x, y, w and h options (#2).
1.1.0
  • Added tolerance option to account for fractional pixel values and “close enough” situations (#1).
1.0.0
  • First stable release.