DOM Elements

⚠️ Relying on Element#query and Element#queryAll is somewhat risky since they’ve been temporarily removed from the current DOM Standard due to significant implementation issues. See related discussions on Stack Overflow and the WHATWG's DOM spec repository on GitHub, and use at your own risk.

DOM Elements is a polyfill that allows you to use the .query and .queryAll methods newly added to the DOM Standard. queryAll returns an instance of the new Elements class which extends Array, allowing you to use map, reduce, filter, forEach, and the like on the returned elements.

Background

The DOM Standard added .query(relativeSelector) and .queryAll(relativeSelector) methods to the ParentNode interface, which is implemented by Document, Element, and DocumentFragment. It also defined a new class, Elements, which extends Array and also has .query and .queryAll.

Usage

You can install the dom-elements package with either npm or bower, or directly download dom-elements.js or dom-elements.min.js and include them in your project.

bower install dom-elements

or

npm install dom-elements

You are also welcome to clone the repo directly and use the dom-elements.js or dom-elements.min.js in the lib directory.

git clone https://github.com/barberboy/dom-elements
npm install
npm start

.query(relativeSelector)

.query() is available on document, documentFragments, individual DOM elements, and the Elements class. It will return the first descendant element which matches the selector, or null if there are zero matches.

var siteHeader = document.query('header');
if (siteHeader) {
  var active = siteHeader.query('.site-menu .active');
}

.queryAll(relativeSelector)

.queryAll is available on document, documentFragments, individual DOM elements and the Elements class. It will return a new instance of Elements containing descendants that match the passed selector, or an instance with no elements if there are no matches.

var collapsibles = document.queryAll('.collapsible');

collapsibles.forEach(function(collapsible){
  var heading = collapsible.query('h1,h2,h3,h4,h5,h6');
  heading.addEventListener('click', function(event) {
    collapsible.classList.toggle('collapsed');
  }, false);
});

The .query and .queryAll methods are also available on the Elements array returned by .queryAll.

 var sections = document.queryAll('section');
 var headingLinks = sections.queryAll(':any(h1,h2,h3,h4,h5,h6) a');

Caveats

• Since we use querySelectorAll and ES5 Array methods, this shim will not work in IE8 and below. See the browser support list at https://ci.testling.com/barberboy/dom-elements.
• This shim (despite it's name—ha!) does not expose the Elements constructor function since there isn't a compelling use-case for instantiating it directly.
• Update: Support for Relative Selectors was added in version 0.1.0 by @bloodyowl.

License

MIT