polyfill-query v1.0.0

query

query is a polyfill for the query and queryAll methods and the Elements collection from the DOM Living Standard.

query is a context-aware version of querySelector, and Elements is a collection of nodes that can also run Array methods.

<section id="main-section">
	<h1>First Heading</h1>

	<section>
		<h1>Subsection Heading</h1>
	</section>
</section>

main = document.getElementById('main-section');

// querySelector has an unexpected quirk
main.querySelector('section h1'); // returns the first heading because it technically matches

// query works as expected
main.query('section h1'); // returns the subsection heading because it is context-aware

This is extremely useful in context-sensitive situations.

<ul>
	<li>
		<a href="#section-1">Section 1</a>
		<ul>
			<li>
				<a href="#section-1-1">Section 1-1</a>
			</li>
		</ul>
	</li>
</ul>

document.query('ul').addEventListener('keydown', function (event) {
	// if the down arrow was pressed from the menu
	if (event.keyCode === 40) {
		var anchor = event.target.closest('a');

		// if an <a> was focused before keydown
		if (anchor) {
			// find the next <a> within a <ul> within this <li>
			var childAnchor = anchor.parentNode.query('ul a');

			// if one exists, focus it
			if (childAnchor) {
				childAnchor.focus();
			}
		}
	}
});

Methods

queryAll

Returns a non-live NodeList of all descendent elements that match the relative CSS selectors.

elementList = baseElement.queryAll(selectors);

query

Returns the first descendent element that matches the relative CSS selectors.

element = baseElement.query(selectors);

Browser compatibility

query and queryAll will work in Android 2.1+, Blackberry 7+, Chrome, Firefox 3.5+, Internet Explorer 8+, iOS Safari 3.2+, Opera 10+, and Safari 3.1+.

Polyfill status

If you like query and queryAll and would like to use it natively, convince Chrome, Opera, Firefox, or Safari to implement it.

query.js is 3.98KB or 570B minified + gzipped.

query.legacy.js is 4.29KB or 614B minified + gzipped.