# CSS Selector Generator JavaScript object that creates a unique CSS selector for a given DOM element or multiple DOM elements. It also generates shorter selectors and is faster and/or more robust than many other libraries - see this [comparison](https://github.com/fczbkk/css-selector-generator-benchmark) and select the best alternative for your use case. ## Install Add the library to your project via NPM or Yarn. ```shell npm install css-selector-generator yarn add css-selector-generator ``` Then include it in your source code: ```javascript import { getCssSelector } from "css-selector-generator"; ``` ## How to use Simplest way to use it is to provide an element reference, without any options. ```html

``` ```javascript getCssSelector(targetElement); // ".myElement" ``` Typical example is to create a selector for any element that the user clicks on: ```javascript // track every click document.body.addEventListener("click", function (event) { // get reference to the element user clicked on const element = event.target; // get unique CSS selector for that element const selector = getCssSelector(element); // do whatever you need to do with that selector console.log("selector", selector); }); ``` ### Usage without NPM If you don't want to use this library with NPM, you can download it directly from the "build" folder and insert it to your HTML document directly. In this case, the library is wrapped in namespace `CssSelectorGenerator`. So the usage would look something like this: ```html

``` ```javascript getCssSelector([firstElement, secondElement]); // ".bbb" ``` If it is not possible to construct single selector for all elements a standalone selector for each element will be generated: ```html

``` ```javascript getCssSelector([firstElement, secondElement]); // "div, span" ``` ### Fallback `getCssSelector` determines the shortest CSS selector for parent -> child relationship, from the input Element until the Root Element. If there is no _unique_ selector available for any of these relationships (parent -> child), a fallback of `*` will be used for this relationship. #wrapper > * > div > .text In some cases, this selector may not be unique (e.g. `#wrapper > * > div > *`). In this case, it will fall back to an entire chain of `:nth-child` selectors like: ":nth-child(2) > :nth-child(4) > :nth-child(1) > :nth-child(12)" ## Options - [`selectors`](#selector-types) - [`root`](#root-element) - [`blacklist`](#blacklist) - [`combineWithinSelector`](#combine-within-selector) - [`combineBetweenSelectors`](#combine-between-selectors) - [`includeTag`](#include-tag) - [`maxCombinations`](#max-combinations) - [`maxCandidates`](#max-candidates) ### Selector types You can choose which types of selectors do you want to use: ```html

``` ```javascript getCssSelector(targetElement, { selectors: ["class"] }); // ".myElement" getCssSelector(targetElement, { selectors: ["tag"] }); // "div" ``` Order of selector types defines their priority: ```javascript getCssSelector(targetElement, { selectors: ["class", "tag"] }); // ".myElement" getCssSelector(targetElement, { selectors: ["tag", "class"] }); // "div" ``` Valid selector types are: - `id` - `class` - `tag` - `attribute` - `nthchild` - `nthoftype` ### Root element You can define root element, from which the selector will be created. If root element is not defined, document root will be used: ```html

``` ```javascript getCssSelector(targetElement); // ".myRootElement > .myElement" getCssSelector(targetElement, { root: document.querySelector(".myRootElement"), }); // ".myElement" ``` ### Blacklist If you want to ignore some selectors, you can put them on the blacklist. Blacklist is an array that can contain either regular expressions, strings and/or functions. In **strings**, you can use an asterisk (`*`) as a wildcard that will match any number of any characters. **Functions** will receive a selector as a parameter. They should always return boolean, `true` if it is a match, `false` if it is not. Any other type of return value will be ignored. ```html

``` ```javascript getCssSelector(targetElement, { blacklist: [".firstClass"] }); // ".secondClass" getCssSelector(targetElement, { blacklist: [".first*"] }); // ".secondClass" getCssSelector(targetElement, { blacklist: [/first/] }); // ".secondClass" getCssSelector(targetElement, { blacklist: [(input) => input.startsWith(".second")], }); // ".secondClass" ``` You can target selectors of any types using the blacklist. ```javascript getCssSelector(targetElement, { blacklist: [ // ID selector "#forbiddenId", // class selector ".forbiddenClass", // attribute selector "[forbidden-attribute]", // tag selector "div", ], }); ``` ### Whitelist Same as `blacklist` option, but instead of ignoring matching selectors, they will be prioritised. ```html

``` ```javascript getCssSelector(targetElement, { whitelist: [".secondClass"] }); // ".secondClass" getCssSelector(targetElement, { whitelist: [".second*"] }); // ".secondClass" getCssSelector(targetElement, { whitelist: [/second/] }); // ".secondClass" ``` ### Combine within selector If set to `true`, the generator will try to look for combinations of selectors within a single type (usually class names) to get better overall selector. ```html

``` ```javascript getCssSelector(targetElement, { combineWithinSelector: false }); // "body > :nth-child(1)" - in this case no single class name is unique getCssSelector(targetElement, { combineWithinSelector: true }); // ".aaa.bbb" ``` This option is set to `true` by default. It can be set to `false` for performance reasons. ### Combine between selectors If set to `true`, the generator will try to look for combinations of selectors between various types (e.g. tag name + class name) to get better overall selector. ```html

``` ```javascript getCssSelector(targetElement, { combineBetweenSelectors: false }); // "body > :nth-child(1)" - in this case no single class name or tag name is unique getCssSelector(targetElement, { combineBetweenSelectors: true }); // "div.aaa" ``` This option is set to `true` by default. It can be set to `false` for performance reasons. ### Include tag This option will add tag selector type to every selector: ```html

``` ```javascript getCssSelector(targetElement, { includeTag: true }); // "div.myElement" ``` ### Max combinations This is a performance optimization option that can help when trying to find a CSS selector within elements that contain large numbers of class names (e.g. because of frameworks that create atomic styles) or other attributes. In such case, the number of possible combinations between class names can be too large (it grows exponentially) and can significantly slow down selector generation. In reality, if the selector is not found within first few combinations, it usually won't be found within the rest of combinations. ```javascript getCssSelector(targetElement, { maxCombinations: 100 }); ``` ### Max candidates Performance optimization option, similar to `maxCombinations`. This does limit a total number of selector candidates for each element. You should use it in cases, when there are not too many class names and attributes, but they are numerous enough to produce large number of combinations between them. ```javascript getCssSelector(targetElement, { maxCandidates: 100 }); ``` ## Bug reports, feature requests and contact If you found any bugs, if you have feature requests or any questions, please, either [file an issue on GitHub][1] or send me an e-mail at [riki@fczbkk.com][2] ## License CSS Selector Generator is published under the [MIT license][3]. [1]: https://github.com/fczbkk/css-selector-generator/issues [2]: mailto:riki@fczbkk.com?subject=CSSSelectorGenerator [3]: https://github.com/fczbkk/css-selector-generator/blob/master/LICENSE

	Stars	Issues	Version	Updated	Created
@medv/finder	1,285	17	3.2.0	2 months ago	6 years ago
css-selector-generator			3.6.7	a month ago	9 years ago
get-unique-selector			1.0.1	5 years ago	5 years ago
selector-from-element			1.0.0	6 years ago	6 years ago

@medv/finder vs css-selector-generator vs get-unique-selector vs selector-from-element

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past