61 | A demonstration of the jQuery Nearest Element plugin. 62 | Check out the code behind it. 63 |
64 |65 | Select an edge/corner to find the nearest blocks (with example code). 66 | Drag the corners to resize the container. 67 |
68 |Available on npm (npm install jquery-nearest)
55 | and Bower (bower install jquery-nearest).
58 | This plugin finds the elements in a page that are closest to a particular point or element, based on pixel dimensions. 59 | This is not to be confused with jQuery's own .closest() method, 60 | which is based on the DOM tree, not pixels. 61 |
62 |63 | There are also helper methods to find elements that are the furthest away from or touching a point or element. 64 |
65 |68 | There are three main methods: 69 |
70 |.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).
77 | Each of the three methods has a utility function on the global jQuery object and a jQuery prototype function for working with element sets.
78 | The following examples all use nearest as the method, but furthest and touching work in the same way.
79 |
$.nearest(pointObject, selector[, options]);
84 | Finds the DOM elements matching selector that are closest to a point or region on the page.
85 |
87 | 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).
88 | 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.
89 |
91 | 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).
92 |
94 | selector is any valid jQuery selector or object that defines an element set to be filtered by the function.
95 |
97 | options is an optional collection of parameters to pass to the function. More details can be found in the options section.
98 |
// Find the image(s) closest to a point 300px in and 100px down from the top left corner
101 | var $closestToPoint = $.nearest({x: 300, y: 100}, 'img');
102 |
103 | // Find the elements with class 'floating' closest to a particular region in the page
104 | var $elemSet = $('.floating');
105 | var $closestToRegion = $.nearest({x: 300, y: 100, w: 200, h: 200}, $elemSet);
106 |
107 | // Find the elements with class 'floating' closest to the right-hand side of the document
108 | var $closestToRightEdge = $.nearest({x: '100%', y: 0, h: '100%'}, '.floating');
109 | $(elem).nearest(selector[, options]);
114 | Finds the DOM elements matching selector that are closest to elem.
115 | If more than one element is in $(elem) then only the first member will be used as a point of reference.
116 |
118 | selector is any valid jQuery selector or object that defines an element set to be filtered by the function.
119 |
121 | options is an optional collection of parameters to pass to the function. More details can be found in the options section.
122 |
var $basicExample = $('#something').nearest('.surrounding');
125 |
126 | // Only the first element in this set will be used for matching
127 | var $set = $('.middle');
128 | // Selector can be any jQuery object
129 | var $convolutedExample = $set.nearest($set.siblings());
130 | $(elemSet).nearest(pointObject[, options]);
135 | Filters elemSet to return only the members that are closest to the point or region defined by pointObject.
136 |
138 | This is effectively the same as calling $.nearest(pointObject, elemSet) but with the benefit of not breaking method chains – see chaining for more details.
139 |
141 | pointObject is an object as defined in the Utility Function reference.
142 |
144 | options is an optional collection of parameters to pass to the function. More details can be found in the options section.
145 |
var $set = $('.filterme');
148 |
149 | // Filter the set by distance to a point
150 | var $closestToPoint = $set.nearest({x: 300, y: 100});
151 |
152 | // Filter the set by distance to a region
153 | var $closestToRegion = $set.nearest({x: 300, y: 100, w: 200, h: 200});
154 |
158 | All methods take an optional options object to further refine the results.
159 | The object can have the following parameters:
160 |
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).220 | A example of using different options can be found on the demonstration page. 221 |
222 | 223 |selector parameter is technically optional in all methods, and will default to div if not present.
227 | However, it is strongly recommended that you pass in a selector,
228 | otherwise the method will loop through every single div element on the page, which –
229 | apart from being slow and computationally expensive – will most likely produce false positives
230 | by matching a reference element's parent nodes.
231 | sameX and sameY options to true in a single call, not both.
234 | If you set both to true, the .nearest() and .furthest() methods will fail to work (it is exactly the same as calling .touching() instead).
235 | onlyX and onlyY options
257 | (PR #7).sameX and sameY options as the inverse replacement for checkHoriz and checkVert
259 | (#9).checkHoriz and checkVert options.container element if the option is present.
267 | (PR #5).tolerance option to account for fractional pixel values and “close enough” situations
283 | (#1).| Source: | " + escapeText( source ) + " |
|---|
| Expected: | " + expected + " |
|---|---|
| Result: | " + actual + " |
| Diff: | " + QUnit.diff( expected, actual ) + " |
| Source: | " + escapeText( source ) + " |
| Result: | " + escapeText( actual ) + " |
|---|---|
| Source: | " + escapeText( source ) + " |