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()

Supported runtime environments

The module is provided in two formats: an ECMAScript (ES) module in

dist/specificity.mjs

dist/specificity.js

Browser

• Directly loaded ES module
• ES module in a precompiled script (using a bundler like Webpack or Rollup)
• Global variable

Node.js

• ES module
• CommonJS module

Browser usage as a directly loaded ES module

Browser usage as an ES module in a precompiled script

Bundlers like Webpack and Rollup import from the

module

package.json

dist/specificity.mjs

import { calculate } from 'specificity';

calculate('ul#nav li.active a');

Browser usage as a global variable

The UMD artefact,

dist/specificity.js

SPECIFICITY

Node.js usage as an ES module

The

main

package.json

dist/specificity

dist/specificity.mjs

dist/specificity.js

When Node.js is run with the

--experimental-modules

import { calculate } from 'specificity';

calculate('ul#nav li.active a');

Node.js usage as a CommonJS module

Otherwise, Node.js will use the UMD artefact, which contains a CommonJS module definition.

const { calculate } = require('specificity');

calculate('ul#nav li.active a');

Calculate function

The

calculate

• 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

Example

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',
    ...
  }
]
*/

Comparing two selectors

Specificity Calculator also exports a

compare

a

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

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

Ordering an array of selectors by specificity

You can pass the

compare

Array.prototype.sort

import { compare } from 'specificity';

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

Command-line usage

Run

npm install specificity

npm install -g specificity

specificity

$ 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

Testing

To install dependencies, run:

npm install

Then to test, run:

npm test