WARNING: Fork

This is a fork of the main library. Please consider using that instead.

optimal select

A library which creates efficient and robust CSS selectors for HTML elements.

The closest you can get if you're looking for a fingerprint of an HTML element

Features

• shortest path and fastest selection in comparison
• configurations allow to define custom options for skip, priority and ignore patterns
• allows single and multiple element as inputs
• provide UMD integration (usage via script, AMD or CommonJS)
• in addition to regular browsers it support the htmlparser2 DOM for virtual environments
• micro library (~ 11kb, no external dependency)

How To Use

Aside of the prebundled versions the library is also available via npm:

npm install --save optimal-select

Integration

import { select } from 'optimal-select' // global: 'OptimalSelect'

document.addEventListener('click', (e) => {
  var selector = select(e.target)
  console.log(selector)
})

Configuration

By default following attributes are ignored for robustness towards changes:

• style (inline styles often temporary and used for dynamic visualizations)
• data-reactid (reacts element identifier which depends on the current DOM structure)
• data-react-checksum (react string rendered markup which depends on the current DOM structure)

To define custom filters you can pass the 'ignore' property as a secondary optional parameter. You can then specify a validation function for the different types (id, class, attribute, tag).

var selector = select(element, {

  // default reference
  root: document,

  skip (traverseNode) {
    // ignore select information of the direct parent
    return traverseNode === element.parentNode
  },

  // define order of attribute processing
  priority: ['id', 'class', 'href', 'src'],

  // define patterns which should't be included
  ignore: {
    class (className) {
      // disregard short classnames
      return className.length < 3
    },

    attribute (name, value, defaultPredicate) {
      // exclude HTML5 data attributes
      return (/data-*/).test(name) || defaultPredicate(name, value)
    },

    // define simplified ignore patterns as a boolean/string/number/regex
    tag: 'div'
  }
})

As shown the root property allows to define the container element (default: document). The skip value allows to define a function, a single node or an array of nodes which should be ignored as the selector is created (default: null). With the priority value can the order of processed attributes be customized. Finally individual filter functions can be defined through ignore.

API

  getQuerySelector (input, [options]) // alias: 'select'

Convenience function which automatically uses either getSingleSelector or getMultiSelector

  getSingleSelector(element, [options])

Retrieve a unique CSS selector of the element Element is a DOM ode

  getMultiSelector(elements, [options])

Retrieve a unique CSS selector of the elements Elements is an array with a list of DOM nodes

  optimize(selector, elements, [options])

Improve the CSS selector

  getCommonAncestor(elements, [options])

Retrieve the closest ancestor of the elements

  getCommonProperties(elements, [options])

Retrieve a set of common properties of the elements

Client & Server

The latest version of optimal-select allows the generation and optimization of selectors on virtual environments. It uses the basic structure the htmlparser2 DOM provides and adds some utilities to create the same results as the browser (note: the withDOMLv1 option has to be enabled). Other libraries like cheerio are built on top of these and therefore compatible.

In contrast to the browser does server environments not have a global context which defines their scope. Therefore one can either be specified explicit through a node using the context options field or automatically extracted from the provided input element. Checkout the example for more details.

TODO

• extend documentation
• add automatic tests (e.g. using jsdom)
• improve child-relation and grouping of getMultiSelector
• define strict option for optimizations of multiple elements
• check attributes for complex classnames
• fix #8 - Full coverage for "nth-of-type" optimization
• consider :not - selector to exclude other elements matching (for multiple element matching consider the :not selector to exclude exceptions)

Development

To build your own version run npm run dev for development (incl. watch) or npm run build for production (minified).