antonmedv/finder

finder

The CSS Selector Generator

Features

• Generates shortest CSS selectors
• Unique CSS selectors per page
• Stable and robust CSS selectors
• Size: 1.5kb (minified & gzipped)

Install

npm install @medv/finder

Usage

import { finder } from '@medv/finder';

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

Example

An example of a generated selector:

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

Configuration

const selector = finder(event.target, {
  root: document.body,
  timeoutMs: 1000,
});

root

Defines the root of the search. Defaults to document.body.

timeoutMs

Timeout to search for a selector. Defaults to 1000ms. After the timeout, finder fallbacks to nth-child selectors.

className

Function that determines if a class name may be used in a selector. Defaults to a word-like class names.

You can extend the default behaviour wrapping the className function:

import { finder, className } from '@medv/finder';

finder(event.target, {
  className: name => className(name) || name.startsWith('my-class-'),
});

tagName

Function that determines if a tag name may be used in a selector. Defaults to () => true.

attr

Function that determines if an attribute may be used in a selector. Defaults to a word-like attribute names and values.

You can extend the default behaviour wrapping the attr function:

import { finder, attr } from '@medv/finder';

finder(event.target, {
  attr: (name, value) => attr(name, value) || name.startsWith('data-my-attr-'),
});

idName

Function that determines if an id name may be used in a selector. Defaults to a word-like id names.

seedMinLength

Minimum length of levels in fining selector. Defaults to 3.

optimizedMinLength

Minimum length for optimising selector. Defaults to 2.

License

MIT