documentQueryStyle

Select element(s) in a document with a computed style that matches the supplied query

Usage

var documentQueryStyle = require('document-query-style');
 
var whiteElements = documentQueryStyle('background-color', 'rgb(255, 255, 255)');
 
var firstAbsoluteTopElement = documentQueryStyle({
    position: 'absolute',
    top: 0
}, true);

API

Query a single CSS property

documentQueryStyle( property, value [, shouldReturnFirstResult] )

• property is a CSS property such as 'background-color' or 'position'.
• value is the value you expect that property to hold.
• shouldReturnFirstResult (optional) should be true if you're only interested in the first matching element.

Returns an array of elements (which could be empty), or if asked for the first matching element, it will either return an element or null if there are no matches.

Query multiple CSS properties

documentQueryStyle( properties [, shouldReturnFirstResult] )

• properties is an object where keys are CSS properties and values are the values you expect those properties to hold
• shouldReturnFirstResult (optional) [as above]

Returns [as above]

Polyfill (well, prollyfill)

Assuming this would eventually become part of the document API, it would most likely expose the methods:

• document.queryStyleAll - which returns all matching elements
• document.queryStyle - which returns the first matching element

You can polyfill that API by calling:

documentQueryStyle.polyfill();

Then you'll be able to do this:

var whiteElements = document.queryStyleAll('background-color', 'rgb(255, 255, 255)');
 
var firstAbsoluteTopElement = document.queryStyle({
    position: 'absolute',
    top: 0
});

Note: rather than using a single funtion with the optional shouldReturnFirstResult argument, each method essentially sets that option for you.

.polyfill API

documentQueryStyle.polyfill([api]);

• api (optional) the object you want to make queryStyleAll and queryStyle available on. This defaults to document, but you might not want to put it there.

Demo

There are examples in the examples directory. Have a look at the index.html file in each example for some typical markup and styling, then look at the corresponding index.js file to see how you'd use documentQueryStyle to query the DOM.

To try out some examples in the browser, run:

$ npm run example

...to get a list of examples, then run:

$ npm run example <example_name>

...and open http://127.0.0.1:9966 in your browser, and chech the browser's console output.

Building standalone version

This module is designed to be required into your project with a tool such as browserify, but if you want to build a standalone module, run:

$ npm install
$ npm run dist

You'll find two new files in the root directory (one of which is minified). Either drop one of the scripts into a page and access documentQueryStyle globally in your project, or use your AMD loader of choice.

Caveats

window.getComputedStyle is used to fetch the current style of each element in the DOM, which means that all units are standardised, i.e.:

• Every size is in px (including fractions based on unit conversions)
• Every colour is in rgb() or rgba()

This library will eventually perform conversions on the values you pass in, but for now, stick to the standard units.

Also, window.getComputedStyle will treat all vendor prefixed properties as separate properties, so you'll have to explicitly check them. documentQueryStyle knows nothing about which property will actually determine the style of an element, in cases where different values are applied.

If an element inherits style from a parent, rather than being defined explicitly, it will be included in the results.

Most importantly, the speed of documentQueryStyle is inversely proportional to the number of elements in the DOM when you call it, so it's probably best not to use it on very complex pages, unless you want to take a performance hit.