A JavaScript module for calculating the specificity of CSS selectors
A JavaScript module for calculating and comparing the specificity of CSS selectors. The module is used on the Specificity Calculator website.
Specificity Calculator is built for CSS Selectors Level 3. Specificity Calculator isn’t a CSS validator. If you enter invalid selectors it will return incorrect results. For example, the negation pseudo-class may only take a simple selector as an argument. Using a psuedo-element or combinator as an argument for
:not()is invalid CSS so Specificity Calculator will return incorrect results.
The module is provided in two formats: an ECMAScript (ES) module in
dist/specificity.mjs, and a Universal Module Definition (UMD) in
dist/specificity.js. This enables support for the following runtime environments:
Browser
Node.js
Bundlers like Webpack and Rollup import from the
modulefield in
package.json, which is set to the ES module artefact,
dist/specificity.mjs.
import { calculate } from 'specificity';calculate('ul#nav li.active a');
The UMD artefact,
dist/specificity.js, sets a global variable,
SPECIFICITY.
The
mainfield in
package.jsonhas an extensionless value,
dist/specificity. This allows Node.js to use either the ES module, in
dist/specificity.mjs, or the CommonJS module, in
dist/specificity.js.
When Node.js is run with the
--experimental-modulesflag or an ES module loader, it will use the ES module artefact.
import { calculate } from 'specificity';calculate('ul#nav li.active a');
Otherwise, Node.js will use the UMD artefact, which contains a CommonJS module definition.
const { calculate } = require('specificity');calculate('ul#nav li.active a');
The
calculatefunction returns an array containing a result object for each selector input. Each result object has the following properties:
selector: the input
specificity: the result as a string e.g.
0,1,0,0
specificityArray: the result as an array of numbers e.g.
[0, 1, 0, 0]
parts: array with details about each part of the selector that counts towards the specificity
calculate('ul#nav li.active a');/* [ { selector: 'ul#nav li.active a', specificity: '0,1,1,3', specificityArray: [0, 1, 1, 3], parts: [ { selector: 'ul', type: 'c', index: 0, length: 2 }, { selector: '#nav', type: 'a', index: 2, length: 4 }, { selector: 'li', type: 'c', index: 5, length: 2 }, { selector: '.active', type: 'b', index: 8, length: 7 }, { selector: 'a', type: 'c', index: 13, length: 1 } ] } ] */
You can use comma separation to pass in multiple selectors:
calculate('ul#nav li.active a, body.ie7 .col_3 h2 ~ h2');/* [ { selector: 'ul#nav li.active a', specificity: '0,1,1,3', ... }, { selector: 'body.ie7 .col_3 h2 ~ h2', specificity: '0,0,2,3', ... } ] */
Specificity Calculator also exports a
comparefunction. This function accepts two CSS selectors or specificity arrays,
aand
b.
-1if
ahas a lower specificity than
b
1if
ahas a higher specificity than
b
0if
ahas the same specificity than
b
compare('div', '.active'); // -1 compare('#main', 'div'); // 1 compare('span', 'div'); // 0 compare('span', [0, 0, 0, 1]); // 0 compare('#main > div', [0, 1, 0, 1]); // 0
You can pass the
comparefunction to
Array.prototype.sortto sort an array of CSS selectors by specificity.
import { compare } from 'specificity';['#main', 'p', '.active'].sort(compare); // ['p', '.active', '#main']
Run
npm install specificityto install the module locally, or
npm install -g specificityfor global installation. Run
specificitywithout arguments to learn about its usage:
$ specificity Usage: specificity Computes specificity of a CSS selector.
Pass a selector as the first argument to get its specificity computed:
$ specificity "ul#nav li.active a" 0,1,1,3
To install dependencies, run:
npm install
Then to test, run:
npm test