Skip to content
JavaScript object that creates unique CSS selector for given object.
CoffeeScript HTML JavaScript
Branch: master
Clone or download
Latest commit ff7bf8f Nov 13, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Release v1.2.0 Nov 13, 2018
example check for empty classname Feb 18, 2014
src remove unused "log" option Nov 13, 2018
test remove unused "log" option Nov 13, 2018
.gitignore gitignore Feb 25, 2014 Release v1.2.0 Nov 13, 2018 fix typo Aug 14, 2018 docs: add options documentation Nov 13, 2018
UNLICENSE init Jan 15, 2014
bower.json chore: add Bower support Nov 26, 2014
package-lock.json feat: added id_blacklist, class_blacklist to options Oct 20, 2018
package.json Release v1.2.0 Nov 13, 2018

CSS Selector Generator

JavaScript object that creates a unique CSS selector for a given DOM element.

It should work fine in any modern browser. It has no external dependencies.

It also generates shorter selectors and is faster and/or more robust than many other libraries - see this comparison and select the best alternative for your use case.

How to use

// first, create instance of the object with default options
my_selector_generator = new CssSelectorGenerator;

// create (or find reference to) any element
my_element = document.createElement('div');

// then you can get unique CSS selector for any referenced element
my_element_selector = my_selector_generator.getSelector(my_element);

The most common use case is finding a unique CSS selector for any referenced element. This is handy if you, for example, let your users select any element on the page by clicking on it:

// track every click
document.body.addEventListener('click', function (event) {
  // get reference to the element user clicked on
  var element =;
  // get unique CSS selector for that element
  var selector = my_selector_generator.getSelector(element);
  // do whatever you need to do with that selector
  console.log('selector', selector);


You can set the options either when creating an instance, or via the setOptions() method:

custom_options = {selectors: ['tag', 'id', 'class']};

// set options when creating an instance
my_selector_generator = new CssSelectorGenerator(custom_options);

// or set options later


default: ['id', 'class', 'tag', 'nthchild']

So far the only option available is the list of types of selectors that will be used when constructing the unique CSS selector. You may want to adjust this list for browser compatibility.

NOTE: The generator keeps the order of selectors when testing for their uniqueness. So if you will set ['class', 'id'] and the element will have unique classname and ID, the resulting selector will contain classname, even if ID is stronger. Also, keep the nthchild selector in last place, because it always generates unique selector and it will prevent using any other selector type behind it.

Available values:

  • 'tag' - Tag selector. E.g. p, div.
  • 'id' - ID selector. E.g. #myElement.
  • 'class' - Class selector. It will get all class names of the element. E.g. .myClass, .firstClass.secondClass.
  • 'nthchild' - N-th child selector. It is supported by IE9 and higher, but it is necessary to create a unique CSS selector for every possible element. You can remove it from the list for backwards browser compatibility, but then make sure to use IDs or class names on each element you want to target. E.g. :nth-child(0)
  • 'attribute' - Attribute selector. Compatible wth IE7 and higher. It will not create matching pairs for element's ID and class name attributes. This type of selector is disabled by default. E.g. [rel=someRel]


default: []

List of ID values, which will be ignored when creating ID selectors.


default: []

List of class names, which will be ignored when creating class selectors.


default: false

If set to true, ID selectors will be prefixed with the tag name.

For example selector for this element

<div id="myElement">...</div>

will look like this: div#myElement.


default: []

List of attribute names, which will be ignored when creating attribute selectors. Attributes "id" and "class" are always be ignored.


default: []

List of attribute names, which will be prioritised when creating attribute selectors.


default: false

If set to true, attribute selector values will be quoted and escaped when needed.

Bug reports, feature requests and contact

If you found any bugs, if you have feature requests or any questions, please, either file an issue on GitHub or send me an e-mail at


CSS Selector Generator is published under the UNLICENSE license. Feel free to use it in any way.

You can’t perform that action at this time.