Skip to content
CSS Selector Generator 🗺
Branch: master
Clone or download
Latest commit d197726 Dec 3, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Fix issues and update deps Oct 5, 2018
.travis.yml Add implementation Feb 20, 2018
LICENSE Update Dec 2, 2018
tsconfig.json Add config to generate declarations May 2, 2018



Build Status

CSS Selector Generator


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


npm install @medv/finder


import finder from '@medv/finder'

document.addEventListener('click', event => {
  const selector = finder(


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(, {
  root: document.body,
  className: (name) => true,
  tagName: (name) => true,
  seedMinLength: 1,
  optimizedMinLength: 2,
  threshold: 1000

root: Element

Root of search, defaults to document.body.

idName: (name: string) => boolean

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

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

className: (name: string) => boolean

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

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

tagName: (name: string) => boolean

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

seedMinLength: number

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.

optimizedMinLength: number

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

threshold: number

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.

Comparison with optimal-select

optimal-select fails to generate selectors some times, and some times generates not unique selectors. finder generates shorter selectors than optimal-select. Also optimal-select now does not have tests and we have :)

For example, on page:

finder optimal-select
fails 0 42
shortest 404 38
longest .story:nth-child(3) .d-lg-flex:nth-child(2) > .width-full:nth-child(1) [class="circle d-flex flex-column flex-justify-center text-center p-4 mx-auto mt-6 mb-3 m-md-3 bg-orange box-shadow-extra-large"] [class="d-block f0-light text-white lh-condensed-ultra mb-2"]
size 2.9 kB 4.58 kB

Google Chrome Extension

Chrome Extension

Generate the unique selectors in your browser by using Chrome Extension



You can’t perform that action at this time.