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]);
83 |
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 |
110 |
111 | $(elem).nearest(selector[, options]);
113 |
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 |
131 |
132 | $(elemSet).nearest(pointObject[, options]);
134 |
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 |
155 |
156 |
158 | All methods take an optional options
object to further refine the results.
159 | The object can have the following parameters:
160 |
includeSelf
false
(not used by the utility methods)$(elem).nearest('.droppable', {includeSelf: true});
onlyX
false
(not used by .touching()
)onlyY
false
(not used by .touching()
)sameX
false
(not used by .touching()
)onlyX: true
if both are provided.sameY
false
(not used by .touching()
)onlyY: true
if both are provided.tolerance
1
container
document
x
, y
, w
and h
– the top left corner of the container is 0%, the bottom right corner is 100%.directionConstraints
empty
"left"
, "right"
, "top"
, "bottom"
["left", "top"]
will only match elements to the top left of the reference point.sort
empty
"nearest"
or "furthest"
checkHoriz
true
– Deprecated in 1.3checkHoriz: false
option is deprecated and will be removed in a future version. Use sameX: true
instead (they are equivalent).checkVert
true
– 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 ) + " |