node package manager

specificity

Calculate the specificity of a CSS selector

Specificity Calculator

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 CSS3 so Specificity Calculator will return incorrect results.

SPECIFICITY.calculate('ul#nav li.active a');   // [{ specificity: '0,1,1,3' }] 
var specificity = require('specificity');
specificity.calculate('ul#nav li.active a');   // [{ specificity: '0,1,1,3' }] 

You can use comma separation to pass in multiple selectors:

SPECIFICITY.calculate('ul#nav li.active a, body.ie7 .col_3 h2 ~ h2');   // [{ specificity: '0,1,1,3' }, { specificity: '0,0,2,3' }] 

The specificity.calculate function 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
var specificity = require('../'),
    result = specificity.calculate('ul#nav li.active a');
 
console.log(result);
 
/* result =
[ {
    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 }
    ]
} ]
*/

Specificity Calculator also exposes a compare function. This function accepts two CSS selectors or specificity arrays, a and b.

  • It returns -1 if a has a lower specificity than b
  • It returns 1 if a has a higher specificity than b
  • It returns 0 if a has the same specificity than b
SPECIFICITY.compare('div', '.active');         // -1 
SPECIFICITY.compare('#main', 'div');           // 1 
SPECIFICITY.compare('span', 'div');            // 0 
SPECIFICITY.compare('span', [0,0,0,1]);        // 0 
SPECIFICITY.compare('#main > div', [0,1,0,1]); // 0 

You can pass the SPECIFICITY.compare function to Array.prototype.sort to sort an array of CSS selectors by specificity.

['#main', 'p', '.active'].sort(SPECIFICITY.compare);   // ['p', '.active', '#main'] 

To install dependencies, run: npm install

Then to test, run: npm test