DOCSEARCHbyAlgolia
Submit Docs

@medv/finder CSS Selector Generator

repository·master·Indexed 23 days ago

https://github.com/antonmedv/finder

A lightweight (1.5kb) CSS selector generator that produces the shortest, unique, and most robust CSS selectors for given DOM elements. It includes a configurable finder() function with options to customize root boundaries, timeouts, and validation logic for IDs, class names, tag names, and attributes.

Tokens
1.3K
Snippets
5
Records
13
Agent score
31%

What's inside @medv/finder

  2. Use the finder function to generate CSS selectors

    master

    Import finder from @medv/finder and pass an element (e.g., event.target) to it. It returns a string representing the shortest, unique, and stable CSS selector for that element.

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

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

  3. Customize className selection logic

    master

    By default, finder uses word-like class names. You can extend this behavior by providing a custom className function. It is recommended to wrap the imported className utility to maintain default behavior for standard names while adding your own logic.

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

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

  4. Customize attr selection logic

    master

    By default, finder uses word-like attribute names and values. You can extend this by providing a custom attr function. Wrap the imported attr utility to combine default logic with custom rules (e.g., allowing specific data- attributes).

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

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

  5. Configure finder options

    master

    The finder function accepts an optional configuration object as its second argument to customize how selectors are generated. Common options include root for the search boundary and timeoutMs to control the search duration before falling back to nth-child selectors.

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

  6. Configure finder options

    master

    You can pass an options object to finder() to customize how selectors are generated. The following options are available:

    OptionTypeDefaultDescription
    rootNodedocument.bodyThe root node used to check for selector uniqueness.
    idNameFunctionidNameFunction to validate if an ID is suitable for a selector.
    classNameFunctionclassNameFunction to validate if a class name is suitable.
    tagNameFunctiontagNameFunction to validate if a tag name is suitable.
    attrFunctionattrFunction to validate if an attribute name/value pair is suitable.
    timeoutMsnumber1000Maximum time in milliseconds to spend searching for a selector.
    seedMinLengthnumber3Minimum path length before starting to yield candidates.
    optimizedMinLengthnumber2Minimum path length required for optimization attempts.
    maxNumberOfPathChecksnumberInfinityMaximum number of unique path candidates to check.

  8. Validate attributes with attr()

    master

    The attr(name, value) function determines if an attribute name and value are suitable for use in a CSS selector.

    By default, it accepts:

    • Specific attribute names: role, name, aria-label, rel, href.
    • data-* attributes if the name is "word-like".
    • Values that are "word-like" and under 100 characters.
    • Values starting with # (e.g., for fragment identifiers) if the remainder is "word-like".