# @medv/finder

> CSS Selector Generator

Latest version **4.0.2** (published 2024-12-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @medv/finder
pnpm add @medv/finder
yarn add @medv/finder
bun add @medv/finder
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 4.0.2 |
| Published | 2024-12-13 |
| First published | 2018-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1493 |
| Author | Anton Medvedev |
| Maintainers | medv |
| Keywords | css, selector, generator |

## Links

- npm: https://www.npmjs.com/package/@medv/finder
- Repository: https://github.com/antonmedv/finder
- Issues: https://github.com/antonmedv/finder/issues
- npm.io page: https://npm.io/package/@medv/finder

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 4.0.2 (latest) — 2024-12-13
- 4.0.1 — 2024-12-13
- 4.0.0 — 2024-12-12
- 3.2.0 — 2024-02-28
- 3.1.0 — 2023-05-05
- 3.0.0 — 2023-03-07
- 2.1.0 — 2021-08-27
- 2.0.0 — 2020-05-23
- 1.1.3 — 2020-05-02
- 1.1.2 — 2019-07-17
- 1.1.1 — 2018-10-05
- 1.1.0 — 2018-08-09
- 1.0.5 — 2018-08-08
- 1.0.4 — 2018-07-23
- 1.0.3 — 2018-05-03
- … 3 more at https://npm.io/package/@medv/finder/versions

## README

# finder

![finder](https://medv.io/assets/finder.png)

**The CSS Selector Generator**

[![Test](https://github.com/antonmedv/finder/actions/workflows/test.yml/badge.svg)](https://github.com/antonmedv/finder/actions/workflows/test.yml)
[![JSR](https://jsr.io/badges/@medv/finder)](https://jsr.io/@medv/finder)

## Features

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

## Install

```bash
npm install @medv/finder
```

## Usage 

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

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

## Example

An example of a generated selector:

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

## Configuration

```js
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:

```js
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:

```js
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](LICENSE)

---
_Source: https://npm.io/package/@medv/finder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._