1.0.9 • Public • Published


Generating unique css selectors is hard. Css-selector-tools makes it easy.

We found other modules were perfectly reliable when generating selectors for content on a website we controlled, but found them lacking when trying to generate reliable css selectors on others' websites. Id and class attributes are the defacto way of generating a selector to an element, but they are also the most commonly adjusted attributes by developers, making them extremely fragile as css selectors. There are just too many dynamic elements in building an html page today for a single selector to work very reliably.

Css-selector-tools works around this difficulty by returning an array of selectors for an element, each with a different strategy for addressing the element, in order of their strength.

If a particular selector result is not unique, and not the element passed, then it is thrown out.

Getting Started

Checkout this simple JSFiddle example

bower install --save css-selector-tools
npm install --save css-selector-tools

Add the script to your page.

<script src="bower_components/css-selector-tools/index.min.js"></script>

Create a test element.

// create test element
var element = document.createElement('DIV');

Now get a set of selectors for the element. Css-selector-tools extends the HTMLElement object with the getSelectors method.

Get array of selectors

var selectors = element.getSelectors();

Get single selector

var selector = element.getSelector();


getSelectors & getSelector

Param Type Description
customAttributes Array Pass an array of custom html attributes which will replace the options specified below.
preferLink Boolean This is a convenience option for cases where the element is nested inside an anchor or button element. It's not uncommon for anchor tags to have further nested structures, and if preferLink is set to true then css-selector-tools will return a selector for any parent link or button found. This is useful when dynamically generating selectors from user click events.

Default css-selector html attributes:

var attributes = [


This is a helper method for adding event listeners to elements, which solves a problem with two click events being sent from the browser for the same user click. For example, when clicking on a label that is on top of an input that is dynamically moved with js. These helper listeners will only return the final event that came in from the same user event.

Param Type Description
type String The kind of event to listen for. HTML Events
callback Function The callback function to call when an event is caught. Passed to the callback is the event object.

Here is an example implementation which will catch any click events that are on, or bubble up to, the body:

document.body.catchSingleEvent('click', function(e) {
  if (!e.isTrusted) return;


Css-selector is in UMD format, so AMD modules are supported.

define('myModule', ['css-selector-tools'], function (css) {
    var element = document.createElement('DIV');
    var selectors = css.getSelectors(element);
    return selectors;

Common JS

If you are using Common JS module format and bundling for the browser (like with browserify) then you can require the module.

var css = require('css-selector-tools');
var selectors = css.getSelectors(element);
// or
var selectors = element.getSelectors();

Package Sidebar


npm i css-selector-tools

Weekly Downloads






Unpacked Size

23.1 kB

Total Files


Last publish


  • afloesch