{"id":13475392,"url":"https://github.com/sindresorhus/element-ready","last_synced_at":"2025-05-14T23:02:11.872Z","repository":{"id":9560651,"uuid":"62587127","full_name":"sindresorhus/element-ready","owner":"sindresorhus","description":"Detect when an element is ready in the DOM","archived":false,"fork":false,"pushed_at":"2025-04-18T18:43:23.000Z","size":257,"stargazers_count":437,"open_issues_count":7,"forks_count":15,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-12T03:25:57.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sindresorhus.png","metadata":{"funding":{"github":"sindresorhus","open_collective":"sindresorhus","buy_me_a_coffee":"sindresorhus","custom":"https://sindresorhus.com/donate"},"files":{"readme":"readme.md","changelog":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2016-07-04T20:46:29.000Z","updated_at":"2025-04-20T04:38:37.000Z","dependencies_parsed_at":"2024-04-17T03:50:20.745Z","dependency_job_id":"5029641d-5390-4fa0-a075-0a7140a12daa","html_url":"https://github.com/sindresorhus/element-ready","commit_stats":{"total_commits":60,"total_committers":10,"mean_commits":6.0,"dds":0.3833333333333333,"last_synced_commit":"5e2474e5f1a48eb43c343fd6d668b12c0ebfc438"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felement-ready","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felement-ready/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felement-ready/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felement-ready/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sindresorhus","download_url":"https://codeload.github.com/sindresorhus/element-ready/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"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":[],"created_at":"2024-07-31T16:01:20.031Z","updated_at":"2025-05-14T23:02:11.812Z","avatar_url":"https://github.com/sindresorhus.png","language":"JavaScript","readme":"# element-ready\n\n\u003e Detect when an element is ready in the DOM\n\n## Install\n\n```sh\nnpm install element-ready\n```\n\n## Usage\n\n```js\nimport elementReady from 'element-ready';\n\nconst element = await elementReady('#unicorn');\n\nconsole.log(element.id);\n//=\u003e 'unicorn'\n```\n\n## API\n\n### elementReady(selector, options?)\n\nReturns a promise for a matching element.\n\n### observeReadyElements(selector, options?)\n\nReturns an async iterable which yields with each new matching element. Useful for user-scripts that modify elements when they are added.\n\n```js\nimport {observeReadyElements} from 'element-ready';\n\nfor await (const element of observeReadyElements('#unicorn')) {\n\tconsole.log(element.id);\n\t//=\u003e 'unicorn'\n\n\tif (element.id === 'elephant') {\n\t\tbreak;\n\t}\n}\n```\n\n#### selector\n\nType: `string`\n\n[CSS selector.](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors)\n\nPrefix the element type to get a better TypeScript return type. For example, `button.my-btn` instead of `.my-btn`.\n\n#### options\n\nType: `object`\n\n##### target\n\nType: `Element | document`\\\nDefault: `document`\n\nThe element that's expected to contain a match.\n\n##### stopOnDomReady\n\nType: `boolean`\\\nDefault: `true`\n\nAutomatically stop checking for the element to be ready after the [DOM ready event](https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event). The promise is then resolved to `undefined`.\n\n##### timeout\n\nType: `number`\\\nDefault: `Infinity`\n\nMilliseconds to wait before stopping the search and resolving the promise to `undefined`.\n\n##### waitForChildren\n\nType: `boolean`\\\nDefault: `true`\n\nSince the current document’s HTML is downloaded and parsed gradually, elements may appear in the DOM before _all_ of their children are “ready”.\n\nBy default, `element-ready` guarantees the element and all of its children have been parsed. This is useful if you want to interact with them or if you want to `.append()` something inside.\n\nBy setting this to `false`, `element-ready` will resolve the promise as soon as it finds the requested selector, regardless of its content. This is ok if you're just checking if the element exists or if you want to read/change its attributes.\n\n##### predicate\n\nType: `(element: HTMLElement) =\u003e boolean`\\\nDefault: `undefined`\n\nA predicate function will be called for each element that matches the selector. If it returns `true`, the element will be returned.\n\nFor example, if the content is dynamic or a selector cannot be specific enough, you could check `.textContent` of each element and only match the one that has the required text.\n\n```html\n\u003cul id=\"country-list\"\u003e\n\t\u003cli\u003ecountry a\u003c/li\u003e\n\t...\n\t\u003cli\u003ewanted country\u003c/li\u003e\n\t...\n\u003c/ul\u003e\n```\n\n```js\nimport elementReady from 'element-ready';\n\nconst wantedCountryElement = await elementReady('#country-list li', {\n\tpredicate: listItemElement =\u003e listItemElement.textContent === 'wanted country'\n});\n```\n\n### elementReadyPromise#stop()\n\nType: `Function`\n\nStop checking for the element to be ready. The stop is synchronous and the original promise is then resolved to `undefined`.\n\nCalling it after the promise has settled or multiple times does nothing.\n\n## Related\n\n- [dom-loaded](https://github.com/sindresorhus/dom-loaded) - Check when the DOM is loaded like `DOMContentLoaded`\n","funding_links":["https://github.com/sponsors/sindresorhus","https://opencollective.com/sindresorhus","https://buymeacoffee.com/sindresorhus","https://sindresorhus.com/donate"],"categories":["JavaScript","Utilities"],"sub_categories":["React Components"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Felement-ready","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsindresorhus%2Felement-ready","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Felement-ready/lists"}