CSS Selector Generator

• Generates shortest selectors
• Unique selectors per page
• Stable and robust selectors
• 2.1 kB gzip and minify size

npm install @medv/finder

Finder can be used via modules:

<script type="module">
  import {finder} from 'https://medv.io/finder/finder.js'
</script>

import {finder} from '@medv/finder'

document.addEventListener('click', event => {
  const selector = finder(event.target)
  console.log(selector)  
})

Example of generated selector:

.blog > article:nth-child(3) .add-comment

finder takes configuration object as second parameters. Here is example of all params with default values:

const selector = finder(event.target, {
  root: document.body,
  className: (name) => true,
  tagName: (name) => true,
  attr: (name, value) => false,
  seedMinLength: 1,
  optimizedMinLength: 2,
  threshold: 1000,
  maxNumberOfTries: 10_000,
  maxRecursionDepth: 10,
})

Root of search, defaults to document.body.

Check if this ID can be used. For example you can restrict using framework specific IDs:

const selector = finder(event.target, {
  idName: name => !name.startsWith('ember')
})

Check if this class name can be used. For example you can restrict using is-* class names:

const selector = finder(event.target, {
  className: name => !name.startsWith('is-')
})

Check if tag name can be used, same as className.

Check if attr name can be used.

Minimum length of levels in fining selector. Starts from 1. For more robust selectors give this param value around 4-5 depending on depth of you DOM tree. If finder hits root this param is ignored.

Minimum length for optimising selector. Starts from 2. For example selector body > div > div > p can be optimized to body p.

Max number of selectors to check before falling into nth-child usage. Checking for uniqueness of selector is very costs operation, if you have DOM tree depth of 5, with 5 classes on each level, that gives you more than 3k selectors to check. finder uses two step approach so it's reaching this threshold in some cases twice. Default 1000 is good enough in most cases.

Max number of tries when we do the optimization. It is a trade-off between optimization and efficiency. Default 10_000 is good enough in most cases.

Max recursion depth when generating selector combinations during search. Defaults to 10. For more complex DOM trees, generating these combinations can be very costly and can max out the CPU. Reducing this option will help in these cases because finder will throw an error instead when this depth has been exceeded.

Generate the unique selectors in your browser by using Chrome Extension

MIT