{"id":20961670,"url":"https://github.com/elchininet/shadow-dom-selector","last_synced_at":"2026-04-27T00:31:21.942Z","repository":{"id":207236963,"uuid":"717853197","full_name":"elchininet/shadow-dom-selector","owner":"elchininet","description":"A very small JavaScript utility to query DOM elements through the Shadow DOM subtrees in a sync or an async way","archived":false,"fork":false,"pushed_at":"2024-04-08T22:23:06.000Z","size":891,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-08T23:36:01.375Z","etag":null,"topics":["dom","dom-query","dom-selector","javascript","javascript-library","library","query-selector","query-selector-all","shadow-dom","shadow-root","shadow-root-query","shadow-root-selector","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elchininet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"elchininet"}},"created_at":"2023-11-12T19:54:37.000Z","updated_at":"2024-04-14T22:30:10.878Z","dependencies_parsed_at":"2023-11-18T03:27:50.674Z","dependency_job_id":"ebfc62a7-cf97-4120-bc82-3224a6f77213","html_url":"https://github.com/elchininet/shadow-dom-selector","commit_stats":null,"previous_names":["elchininet/shadow-dom-selector"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elchininet%2Fshadow-dom-selector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elchininet%2Fshadow-dom-selector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elchininet%2Fshadow-dom-selector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elchininet%2Fshadow-dom-selector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elchininet","download_url":"https://codeload.github.com/elchininet/shadow-dom-selector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243358306,"owners_count":20277995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dom","dom-query","dom-selector","javascript","javascript-library","library","query-selector","query-selector-all","shadow-dom","shadow-root","shadow-root-query","shadow-root-selector","typescript"],"created_at":"2024-11-19T02:15:15.133Z","updated_at":"2025-12-30T00:39:32.989Z","avatar_url":"https://github.com/elchininet.png","language":"TypeScript","funding_links":["https://github.com/sponsors/elchininet"],"categories":[],"sub_categories":[],"readme":"# shadow-dom-selector\n\nA very small JavaScript utility to query DOM elements through the [Shadow DOM] subtrees in a sync or an async way.\n\n[![Deployment Status](https://github.com/elchininet/shadow-dom-selector/actions/workflows/deploy.yaml/badge.svg)](https://github.com/elchininet/shadow-dom-selector/actions/workflows/deploy.yaml)\n[![Tests](https://github.com/elchininet/shadow-dom-selector/actions/workflows/tests.yaml/badge.svg)](https://github.com/elchininet/shadow-dom-selector/actions/workflows/tests.yaml)\n[![Coverage Status](https://coveralls.io/repos/github/elchininet/shadow-dom-selector/badge.svg?branch=master)](https://coveralls.io/github/elchininet/shadow-dom-selector?branch=master)\n[![npm version](https://badge.fury.io/js/shadow-dom-selector.svg)](https://badge.fury.io/js/shadow-dom-selector)\n[![downloads](https://img.shields.io/npm/dw/shadow-dom-selector)](https://www.npmjs.com/package/shadow-dom-selector)\n\n## Introduction\n\nHaving a DOM tree formed of Shadow DOM subtrees like the next one:\n\n```html\n\u003cbody\u003e\n  \u003csection\u003e\n    #shadow-root (open)\n      \u003ch1\u003eTitle\u003c/h1\u003e\n      \u003carticle\u003e\n        #shadow-root (open)\n          \u003ch2\u003eSubtitle\u003c/h2\u003e\n          \u003cul\u003e\n            \u003cli\u003eItem 1\u003c/li\u003e\n            \u003cli\u003eItem 2\u003c/li\u003e\n            \u003cli\u003eItem 1\u003c/li\u003e\n          \u003c/ul\u003e\n      \u003c/article\u003e\n  \u003c/section\u003e\n\u003c/body\u003e\n```\nIf one wants to query for the `li` elements, it is required to do this:\n\n```javascript\nconst firstLi = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot.querySelector('ul \u003e li');\n\nconst allLis = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot.querySelectorAll('ul \u003e li');\n\nconst shadow = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot;\n```\n\n`shadow-dom-selector` allows you to do the same in the next way:\n\n```javascript\n// $ character at the end of a selector means to select its Shadom DOM\n\nimport {\n  querySelector,\n  querySelectorAll,\n  shadowRootQuerySelector,\n  deepQuerySelector,\n  deepQuerySelectorAll\n} from 'shadow-dom-selector';\n\nconst firstLi = querySelector('section$ article$ ul \u003e li');\nconst allLis = querySelectorAll('section$ article$ ul \u003e li');\nconst shadow = shadowRootQuerySelector('section$ article$');\n\nconst deepFirstLi = deepQuerySelector('li');\nconst deepAllLi = deepQuerySelectorAll('li');\n```\n\nIt will traverse all the Shadow DOM subtrees removing all the hassle of writing long concatenated queries.\n\n### It checks for the existence of elements\n\nWith the same previous DOM tree, if we do this:\n\n```javascript\nconst element = document.querySelector('article').shadowRoot.querySelector('div').shadowRoot.querySelector('section \u003e h1');\n```\n\nIt will throw an error, because none of the elements in those queries exist. If you don‘t know if the elements exist or not, you will require to wrap all the code in conditions or use [optional chaining] if your target is `ES2015` or greater:\n\n```javascript\n// With conditions\nconst article = document.querySelector('article');\nif (article) {\n  const articleShadowRoot = article.shadowRoot;\n  if (articleShadowRoot) {\n    const div = articleShadowRoot.querySelector('div');\n    if (div) {\n      const shadow = div.shadowRoot;\n      if (shadow) {\n        const element = shadow.querySelector('section \u003e h1');\n        const elements = shadow.querySelectorAll('p');\n      }\n    }\n  }\n}\n\n// With optional chaining in ES2015+\nconst shadow = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot;\nconst element = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot?.querySelector('section \u003e h1');\nconst elements = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot?.querySelectorAll('p');\n```\n\nWhich will return `undefined` if some element doesn‘t exist. With `shadow-dom-selector`, you just need to write the query and it will return the same that is returned by the native `querySelector` and `querySelectorAll` if the query cannot be satisfied.\n\n```javascript\nimport {\n  querySelector,\n  querySelectorAll,\n  shadowRootQuerySelector,\n  deepQuerySelector,\n  deepQuerySelectorAll\n} from 'shadow-dom-selector';\n\nconst shadow = shadowRootQuerySelector('article$ div$'); // null\nconst element = querySelector('article$ div$ section \u003e h1'); // null\nconst elements = querySelectorAll('article$ div$ p'); // empty NodeList\nconst deepElement = deepQuerySelector('span') // null;\nconst deepElements = deepQuerySelectorAll('p'); // empty NodeList\n```\n\n### Async queries\n\nIf the elements are not already rendered into the DOM in the moment that the query is made you will receive `null`. `shadow-dom-selector` allows you to wait for the elements to appear deciding how many times it will try to query for the element before giving up and returning `null` or an empty `NodeList`.\n\n```javascript\n// Using the async methods\nimport {\n  asyncQuerySelector,\n  asyncQuerySelectorAll,\n  asyncShadowRootQuerySelector,\n  asyncDeepQuerySelector,\n  asyncDeepQuerySelectorAll\n} from 'shadow-dom-selector';\n\nasyncShadowRootQuerySelector('article$ div$')\n  .then((shadowRoot) =\u003e {\n      // Do stuff with the shadowRoot\n      // If it is not found after all the retries, it will return null\n  });\n\nasyncQuerySelector('article$ div$ section \u003e h1')\n  .then((h1) =\u003e {\n      // Do stuff with the h1 element\n      // If it is not found after all the retries, it will return null\n  });\n\nasyncQuerySelectorAll('article$ div$ p')\n  .then((paragraphs) =\u003e {\n      // Do stuff with the paragraphs\n      // If they are not found after all the retries, it will return an empty NodeList\n  });\n\nasyncDeepQuerySelector('h1')\n  .then((h1) =\u003e {\n      // Do stuff with the h1 element\n      // If it is not found after all the retries, it will return null\n  });\n\nasyncDeepQuerySelectorAll('p')\n  .then((paragraphs) =\u003e {\n      // Do stuff with the paragraphs\n      // If they are not found after all the retries, it will return an empty NodeList\n  });\n\n// Using de AsyncSelector class\nimport { AsyncSelector } from 'shadow-dom-selector';\n\nconst selector = new AsyncSelector();\n\nselector.query('article').$.query('div').$.element\n  .then((shadowRoot) =\u003e {\n    // Do stuff with the shadowRoot\n    // If it is not found after all the retries, it will return null\n  });\n\nselector.query('article').$.query('div').$.query('section \u003e h1').element\n  .then((h1) =\u003e {\n    // Do stuff with the h1 element\n    // If it is not found after all the retries, it will return null\n  });\n\nselector.query('article').$.query('div').$.query('p').all\n  .then((paragraphs) =\u003e {\n    // Do stuff with the paragraphs\n    // If they are not found after all the retries, it will return an empty NodeList\n  });\n\nselector.deepQuery('h1').element\n  .then((h1) =\u003e {\n    // Do stuff with the h1 element\n    // If it is not found after all the retries, it will return null\n  });\n\nselector.deepQuery('p').all\n  .then((paragraphs) =\u003e {\n    // Do stuff with the paragraphs\n    // If they are not found after all the retries, it will return an empty NodeList\n  });\n```\n\nEither the async methods or the async dot notation allow you to to specify the amount of retries and the delay between each one of them. Consult the [API](#api) section for more details.\n\n## Install\n\n#### npm\n\n```bash\nnpm install shadow-dom-selector\n```\n\n#### yarn\n\n```bash\nyarn add shadow-dom-selector\n```\n\n#### PNPM\n\n```bash\npnpm add shadow-dom-selector\n```\n\n#### In the browser\n\nIt is possible to include a compiled version of the package directly in an HTML file. It will create a global `ShadowDomSelector` object containing all the exported functions that can be accessed from anywhere in your JavaScript code.\n\n1. Copy the JavaScript file `shadow-dom-selector-web.js`, located in the root of the `dist/` folder\n2. Put it in the folder that you prefer in your web server\n3. Include it in your HTML file\n\n```html\n\u003cscript src=\"wherever/you/want/to/place/shadow-dom-selector-web.js\"\u003e\u003c/script\u003e\n```\n\n```javascript\n/* There will be a global variable named ShadowDomSelector containing all the functions */\nShadowDomSelector.querySelector;\nShadowDomSelector.deepQuerySelector;\nShadowDomSelector.querySelectorAll;\nShadowDomSelector.deepQuerySelectorAll;\nShadowDomSelector.shadowRootQuerySelector;\nShadowDomSelector.asyncQuerySelector;\nShadowDomSelector.asyncDeepQuerySelector;\nShadowDomSelector.asyncQuerySelectorAll;\nShadowDomSelector.asyncDeepQuerySelectorAll;\nShadowDomSelector.asyncShadowRootQuerySelector;\nShadowDomSelector.AsyncSelector;\n```\n\n## API\n\n#### querySelector\n\nPerforms a query selection passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nquerySelector(selectors): Element | null;\n```\n\n```typescript\nquerySelector(root, selectors): Element | null;\n```\n\n| Parameter    | Optional      | Description                                        |\n| ------------ | ------------- | -------------------------------------------------- |\n| `selectors`  | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`       | yes           | The element from where the query should be performed, it defaults to `document` |\n\n#### deepQuerySelector\n\nPerforms a query selection of an element searching for it recursively in the whole DOM tree even if it needs to pass through the `shadowRoots` of elements.\n\n\u003eNote: use this method carefully, depending on the extension of your DOM tree, it could be an expensive task in terms of resources. Do this when you need to query for an element that could appear in any part of the DOM tree so you don‘t know its exact position, otherwise, the `querySelector` method is recommended.\n\n```typescript\ndeepQuerySelector(selectors): Element | null;\n```\n\n```typescript\ndeepQuerySelector(root, selectors): Element | null;\n```\n\n| Parameter    | Optional      | Description                                        |\n| ------------ | ------------- | -------------------------------------------------- |\n| `selectors`  | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`       | yes           | The element from where the query should be performed, it defaults to `document` |\n\n#### querySelectorAll\n\nPerforms a `querySelectionAll` query passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nquerySelectorAll(selectors): NodeListOf\u003cElement\u003e;\n```\n\n```typescript\nquerySelectorAll(root, selectors): NodeListOf\u003cElement\u003e;\n```\n\n| Parameter    | Optional      | Description                                        |\n| ------------ | ------------- | -------------------------------------------------- |\n| `selectors`  | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`       | yes           | The element from where the query should be performed, it defaults to `document` |\n\n#### deepQuerySelectorAll\n\nPerforms a `querySelectionAll` query of elements searching for them recursively in the whole DOM tree even if it needs to pass through the `shadowRoots` of elements.\n\n\u003eNote: use this method carefully, depending on the extension of your DOM tree, it could be an expensive task in terms of resources. Do this when you need to query for elements that could appear in any part of the DOM tree so you don‘t know their exact position, otherwise, the `querySelectionAll` method is recommended.\n\n```typescript\ndeepQuerySelectorAll(selectors): NodeListOf\u003cElement\u003e;\n```\n\n```typescript\ndeepQuerySelectorAll(root, selectors): NodeListOf\u003cElement\u003e;\n```\n\n| Parameter    | Optional      | Description                                        |\n| ------------ | ------------- | -------------------------------------------------- |\n| `selectors`  | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`       | yes           | The element from where the query should be performed, it defaults to `document` |\n\n#### shadowRootQuerySelector\n\nPerforms a query selection of a `shadowRoot` passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nshadowRootQuerySelector(selectors): ShadowRoot | null;\n```\n\n```typescript\nshadowRootQuerySelector(root, selectors): ShadowRoot | null;\n```\n\n| Parameter    | Optional      | Description                                        |\n| ------------ | ------------- | -------------------------------------------------- |\n| `selectors`  | no            | A string containing one or more selectors to match. Selectors must end in a Shadow DOM (`$`) |\n| `root`       | yes           | The element from where the query should be performed, it defaults to `document` |\n\n#### asyncQuerySelector\n\nPerforms an asynchronous query selection passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nasyncQuerySelector(selectors): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncQuerySelector(root, selectors): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncQuerySelector(selectors, asyncParams): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncQuerySelector(root, selectors, asyncParams): Promise\u003cElement | null\u003e;\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `selectors`   | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`        | yes           | The element from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\n#### asyncDeepQuerySelector\n\nPerforms an asynchronous query selection of an element searching for it recursively in the whole DOM tree even if it needs to pass through the `shadowRoots` of elements.\n\n\u003eNote: use this method carefully, depending on the extension of your DOM tree, it could be an expensive task in terms of resources. Do this when you need to query for an element that could appear in any part of the DOM tree so you don‘t know its exact position, otherwise, the `asyncQuerySelector` method is recommended.\n\n```typescript\nasyncDeepQuerySelector(selectors): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncDeepQuerySelector(root, selectors): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncDeepQuerySelector(selectors, asyncParams): Promise\u003cElement | null\u003e;\n```\n\n```typescript\nasyncDeepQuerySelector(root, selectors, asyncParams): Promise\u003cElement | null\u003e;\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `selectors`   | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`        | yes           | The element from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\n#### asyncQuerySelectorAll\n\nPerforms an asynchronous `querySelectionAll` query passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nasyncQuerySelectorAll(selectors): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncQuerySelectorAll(root, selectors): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncQuerySelectorAll(selectors, asyncParams): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncQuerySelectorAll(root, selectors, asyncParams): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `selectors`   | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`        | yes           | The element from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\n#### asyncDeepQuerySelectorAll\n\nPerforms an asynchronous `querySelectionAll` query of elements searching for them recursively in the whole DOM tree even if it needs to pass through the `shadowRoots` of elements.\n\n\u003eNote: use this method carefully, depending on the extension of your DOM tree, it could be an expensive task in terms of resources. Do this when you need to query for elements that could appear in any part of the DOM tree so you don‘t know their exact position, otherwise, the `asyncQuerySelectorAll` method is recommended.\n\n```typescript\nasyncDeepQuerySelectorAll(selectors): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncDeepQuerySelectorAll(root, selectors): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncDeepQuerySelectorAll(selectors, asyncParams): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n```typescript\nasyncDeepQuerySelectorAll(root, selectors, asyncParams): Promise\u003cNodeListOf\u003cElement\u003e\u003e;\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `selectors`   | no            | A string containing one or more selectors to match. Selectors may not end in a Shadow DOM (`$`) |\n| `root`        | yes           | The element from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\n#### asyncShadowRootQuerySelector\n\nPerforms an asynchronous query selection of a `shadowRoot` passing through the `shadowRoot` of elements if you add `$` after them.\n\n```typescript\nasyncShadowRootQuerySelector(selectors): Promise\u003cShadowRoot | null\u003e;\n```\n\n```typescript\nasyncShadowRootQuerySelector(root, selectors): Promise\u003cShadowRoot | null\u003e;\n```\n\n```typescript\nasyncShadowRootQuerySelector(selectors, asyncParams): Promise\u003cShadowRoot | null\u003e;\n```\n\n```typescript\nasyncShadowRootQuerySelector(root, selectors, asyncParams): Promise\u003cShadowRoot | null\u003e;\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `selectors`   | no            | A string containing one or more selectors to match. Selectors must end in a Shadow DOM (`$`) |\n| `root`        | yes           | The element from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\n#### AsyncSelector class\n\nThis class creates an instance of an element that could be used to perform asynchronous query selections in the DOM tree passing through the `shadowRoot` of elements.\n\n```typescript\nnew AsyncSelector();\n```\n\n```typescript\nnew AsyncSelector(root);\n```\n\n```typescript\nnew AsyncSelector(root, asyncParams);\n```\n\n| Parameter     | Optional      | Description                                        |\n| ------------- | ------------- | -------------------------------------------------- |\n| `root`        | yes           | The element or shadowRoot from where the query should be performed, it defaults to `document` |\n| `asyncParams` | yes           | An object containing the parameters which control the retries |\n\n```typescript\n// asyncParams properties\n{\n  retries?: number; // how many retries before giving up (defaults to 10)\n  delay?: number; // delay between each retry (defaults to 10)\n}\n```\n\nThe instances of this class have the next properties:\n\n| Property         | Type                                     | Description                                                      |\n| ---------------- | ---------------------------------------- | ---------------------------------------------------------------- |\n| `element`        | `Promise\u003cElement \\| ShadowRoot \\| null\u003e` | A promise that resolves in the queried element                   |\n| `all`            | `Promise\u003cNodeListOf\u003cElement\u003e\u003e`           | A promise that resolves in a Nodelist with all queried elements  |\n| `$`              | `Promise\u003cShadowRoot \\| null\u003e`            | A promise that resolves in the shadowRoot of the queried element |\n| `asyncParams`    | Same `asyncParams` previously shown      | An object containing the parameters which control the retries    |\n\nAnd the next methods:\n\n| Method                        | Return                     | Description                                                      |\n| ----------------------------- | -------------------------- | ---------------------------------------------------------------- |\n| `eq(index: number)`           | `Promise\u003cElement \\| null\u003e` | Returns a promise that resolves in the element in the index position of the queried elements (startig from `0`) |\n| `query(selector: string)`     | `AsyncSelector`            | Performs a query and returns a new AsyncSelector instance |\n| `deepQuery(selector: string)` | `AsyncSelector`            | Performs a deep query (even through elements' shadowRoot) ans returns a new AsyncSelector instance |\n\n\n##### Examples of the AsyncSelector class\n\n```typescript\nconst selector = new AsyncSelector(); // Starting to query in the document with the default asyncParams\nawait selector.element === document;\nawait selector.all; // Empty Node list\nawait selector.$; // null\nawait selector.eq(0); // null\n```\n\n```typescript\nconst selector = AsyncSelector({\n  retries: 100,\n  delay: 50\n}); // Starting to query in the document with custom asyncParams\nawait selector.query('section').$.element === document.querySelector('section').shadowRoot;\nawait selector.query('section').$.all; // Empty Node list\nawait selector.query('section').$.query('article').all === document.querySelector('section').shadowRoot.querySelectorAll('article');\nawait selector.query('section').$.query('ul li').eq(1) === document.querySelector('section').shadowRoot.querySelectorAll('ul li')[1];\nawait selector.deepQuery('li.delayed-li').element; // try to query the element deep in the shadowDOM tree until the retries/delay expire\nawait selector.deepQuery('li.delayed-li').all; // try to perform a querySelectorAll deep in the shadowDOM tree until the retries/delay expire\nselector.query('section').$.query('article').asyncParams; // { retries: 100, delay: 50 }\n```\n\n[Shadow DOM]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM\n[optional chaining]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felchininet%2Fshadow-dom-selector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felchininet%2Fshadow-dom-selector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felchininet%2Fshadow-dom-selector/lists"}