{"id":15042528,"url":"https://github.com/sindresorhus/dom-mutations","last_synced_at":"2025-04-06T11:08:21.469Z","repository":{"id":208512075,"uuid":"721821057","full_name":"sindresorhus/dom-mutations","owner":"sindresorhus","description":"Observe changes to the DOM using an async iterable — A nicer API for MutationObserver","archived":false,"fork":false,"pushed_at":"2024-08-18T07:47:27.000Z","size":10,"stargazers_count":211,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T09:09:32.257Z","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":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"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},"funding":{"github":"sindresorhus","open_collective":"sindresorhus","buy_me_a_coffee":"sindresorhus","custom":"https://sindresorhus.com/donate"}},"created_at":"2023-11-21T20:54:12.000Z","updated_at":"2025-03-28T05:26:35.000Z","dependencies_parsed_at":"2024-04-17T07:26:06.515Z","dependency_job_id":"8365e463-1ccd-471d-8a84-53f0d41d8f79","html_url":"https://github.com/sindresorhus/dom-mutations","commit_stats":{"total_commits":7,"total_committers":1,"mean_commits":7.0,"dds":0.0,"last_synced_commit":"5916028b0635f949cc0f06688729198981c89a6c"},"previous_names":["sindresorhus/dom-mutations"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fdom-mutations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fdom-mutations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fdom-mutations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fdom-mutations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sindresorhus","download_url":"https://codeload.github.com/sindresorhus/dom-mutations/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471520,"owners_count":20944158,"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-09-24T20:47:27.166Z","updated_at":"2025-04-06T11:08:21.448Z","avatar_url":"https://github.com/sindresorhus.png","language":"JavaScript","funding_links":["https://github.com/sponsors/sindresorhus","https://opencollective.com/sindresorhus","https://buymeacoffee.com/sindresorhus","https://sindresorhus.com/donate"],"categories":["JavaScript","⚙️ Backend \u0026 APIs"],"sub_categories":[],"readme":"# dom-mutations\n\n\u003e Observe changes to the DOM using an async iterable — A nicer API for [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)\n\nThis package only works in the browser.\n\n## Install\n\n```sh\nnpm install dom-mutations\n```\n\n## Usage\n\n```js\nimport domMutations from 'dom-mutations';\n\nconst target = document.querySelector('#unicorn');\n\nfor await (const mutation of domMutations(target, {childList: true})) {\n\tconsole.log('Mutation:', mutation);\n}\n```\n\n## API\n\n### domMutations(target, options?) \u003csup\u003e(default export)\u003c/sup\u003e\n\nAccepts the same arguments as [`MutationObserver#observe()`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#parameters) with an additional optional [`signal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal) option to abort the observation. If the signal is triggered, the async iterable throws an [abort error](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort).\n\nReturns an [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) that yields [`MutationRecord`](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects representing individual mutations.\n\n### batchedDomMutations(target, options?) \u003csup\u003e(named export)\u003c/sup\u003e\n\nSimilar to `domMutations()`, but yields batches of [`MutationRecord`](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects, each batch representing a group of mutations captured together. This method is less convenient, but can be useful in some cases when you need to handle mutations together as a group.\n\n```js\nimport {batchedDomMutations} from 'dom-mutations';\n\nconst target = document.querySelector('#unicorn');\n\nfor await (const mutations of batchedDomMutations(target, {childList: true})) {\n\tconsole.log('Batch of mutations:', mutations);\n}\n```\n\n## FAQ\n\n### How do I stop the iteration?\n\nSimply `return` or `break` in the loop body.\n\n### How do I stop the iteration from the outside?\n\n**Triggering the iterator to return**\n\n```js\nimport domMutations from 'dom-mutations';\n\nconst target = document.querySelector('#unicorn');\n\nconst mutationIterator = domMutations(target, {childList: true})[Symbol.asyncIterator]();\n\n(async () =\u003e {\n\tfor await (const mutation of mutationIterator) {\n\t\tconsole.log('Mutation:', mutation);\n\t}\n})();\n\nsetTimeout(() =\u003e {\n\tmutationIterator.return();\n}, 10000);\n```\n\n**Using a variable**\n\nThis has the downside of not ending the iteration until the next mutation.\n\n```js\nimport domMutations from 'dom-mutations';\n\nconst target = document.querySelector('#unicorn');\n\nlet shouldStop = false;\n\n(async () =\u003e {\n\tfor await (const mutation of domMutations(target, {childList: true})) {\n\t\tif (shouldStop) {\n\t\t\tbreak;\n\t\t}\n\n\t\tconsole.log('Mutation:', mutation);\n\t}\n})();\n\nsetTimeout(() =\u003e {\n\tshouldStop = true;\n}, 10000);\n```\n\n**Using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)**\n\nUnlike the above approaches, this will make the iterable throw an [abort error](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort).\n\n```js\nimport domMutations from 'dom-mutations';\n\nconst target = document.querySelector('#unicorn');\nconst controller = new AbortController();\nconst {signal} = controller;\n\n(async () =\u003e {\n\tfor await (const mutation of domMutations(target, {childList: true, signal})) {\n\t\tconsole.log('Mutation:', mutation);\n\t}\n})();\n\nsetTimeout(() =\u003e {\n\tcontroller.abort();\n}, 10000);\n```\n\n## Related\n\n- [request-animation-frames](https://github.com/sindresorhus/request-animation-frames) - Use `requestAnimationFrame` as an async iterable, in any JavaScript environment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fdom-mutations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsindresorhus%2Fdom-mutations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fdom-mutations/lists"}