{"id":18478566,"url":"https://github.com/growthbook/dom-mutator","last_synced_at":"2025-07-06T17:38:27.083Z","repository":{"id":53802247,"uuid":"336028605","full_name":"growthbook/dom-mutator","owner":"growthbook","description":"Apply persistent DOM Mutations on top of HTML you don't control.","archived":false,"fork":false,"pushed_at":"2024-12-03T21:01:18.000Z","size":222,"stargazers_count":8,"open_issues_count":3,"forks_count":4,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-08T15:47:28.159Z","etag":null,"topics":["dom","dom-manipulation","mutationobserver","react"],"latest_commit_sha":null,"homepage":"https://growthbook.github.io/dom-mutator/","language":"TypeScript","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/growthbook.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}},"created_at":"2021-02-04T17:20:33.000Z","updated_at":"2024-12-03T21:01:23.000Z","dependencies_parsed_at":"2023-10-20T01:15:03.930Z","dependency_job_id":"d647b7c5-17f1-4a06-ab66-75e51a846622","html_url":"https://github.com/growthbook/dom-mutator","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/growthbook/dom-mutator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growthbook%2Fdom-mutator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growthbook%2Fdom-mutator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growthbook%2Fdom-mutator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growthbook%2Fdom-mutator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/growthbook","download_url":"https://codeload.github.com/growthbook/dom-mutator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growthbook%2Fdom-mutator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263943719,"owners_count":23533637,"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-manipulation","mutationobserver","react"],"created_at":"2024-11-06T12:10:34.762Z","updated_at":"2025-07-06T17:38:27.061Z","avatar_url":"https://github.com/growthbook.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DOM Mutator\n\nFor those times you need to apply persistent DOM changes on top of HTML you don’t control.\n\nView demo: https://growthbook.github.io/dom-mutator/\n\n```ts\nconst mutation = mutate.html('#greeting', (html) =\u003e html + ' world');\n\n// works even if the selector doesn't exist yet\ndocument.body.innerHTML += \"\u003cdiv id='greeting'\u003ehello\u003c/div\u003e\";\n\n// \"hello world\"\n\n// re-applies if there's an external change\ndocument.getElementById('greeting').innerHTML = 'hola';\n\n// \"hola world\"\n\n// Revert to the last externally set value\nmutation.revert();\n\n// \"hola\"\n```\n\n```ts\nimport mutate from 'dom-mutator';\n\nmutate.html('h1', (html) =\u003e html.toUpperCase());\n\nmutate.classes('div.greeting', (classes) =\u003e classes.add('new-class'));\n\nmutate.attribute(\n    '.get-started',\n    'title',\n    (oldVal) =\u003e 'This is my new title attribute'\n);\n```\n\nFeatures:\n\n-   No dependencies, written in Typescript, 100% test coverage\n-   Super fast and light-weight (1Kb gzipped)\n-   Persists mutations even if the underlying element is updated externally (e.g. by a React render)\n-   Picks up new matching elements that are added to the DOM\n-   Easily remove a mutation at any time\n\n![Build Status](https://github.com/growthbook/dom-mutator/workflows/CI/badge.svg)\n\n## Installation\n\nInstall with npm or yarn (recommended):\n\n`yarn add dom-mutator` OR `npm install --save dom-mutator`.\n\n```js\nimport mutate from \"dom-mutator\";\n...\n```\n\nOR use with unpkg:\n\n```html\n\u003cscript type=\"module\"\u003e\n    import mutate from \"https://unpkg.com/dom-mutator/dist/dom-mutator.esm.js\";\n    ...\n\u003c/script\u003e\n```\n\n## Usage\n\nThere are 4 mutate methods available: `html`, `classes`, `attribute`, and `declarative`.\n\n### html\n\nMutate an element's innerHTML\n\n```ts\n// Signature\nmutate.html(selector: string, (oldInnerHTML: string) =\u003e string);\n\n// Example\nmutate.html(\"h1\", x =\u003e x.toUpperCase());\n```\n\n### classes\n\nMutate the set of classes for an element\n\n```ts\n// Signature\nmutate.classes(selector: string, (classes: Set\u003cstring\u003e) =\u003e void);\n\n// Example\nmutate.classes(\"h1\", (classes) =\u003e {\n  classes.add(\"green\");\n  classes.remove(\"red\");\n});\n```\n\n### attribute\n\nMutate the value of an HTML element's attribute\n\n```ts\n// Signature\nmutate.attribute(selector: string, attribute: string, (oldValue: string) =\u003e string);\n\n// Example\nmutate.attribute(\".link\", \"href\", (href) =\u003e href + \"?foo\");\n```\n\n### position\n\nMutate the position of an HTML element by supplying a target parent element to append it to (and optional sibling element to place it next to).\n\n```ts\n// Signature\nmutate.position(selector: string, () =\u003e ({ parentSelector: string; insertBeforeSelector?: string; }));\n\n// Example\nmutate.attribute(\".link\", () =\u003e ({ parentSelector: '.parent', insertBeforeSelector: 'p.body' }));\n```\n\n### declarative\n\nMutate the html, classes, or attributes using a declarative syntax instead of callbacks.\nPerfect for serialization.\n\n```ts\n// Signature\nmutate.declarative({\n    selector: string,\n    action: 'set' | 'append' | 'remove',\n    attribute: 'html' | 'class' | string,\n    value: string,\n});\n\n// Examples\nconst mutations = [\n    {\n        selector: 'h1',\n        action: 'set',\n        attribute: 'html',\n        value: 'new text',\n    },\n    {\n        selector: '.get-started',\n        action: 'remove',\n        attribute: 'class',\n        value: 'green',\n    },\n    {\n        selector: 'a',\n        action: 'append',\n        attribute: 'href',\n        value: '?foo',\n    },\n    {\n        selector: 'a',\n        action: 'set',\n        attribute: 'position',\n        parentSelector: '.header',\n        insertBeforeSelector: '.menu-button',\n    },\n];\nmutations.forEach((m) =\u003e mutate.declarative(m));\n```\n\n## How it Works\n\nWhen you create a mutation, we start watching the document for elements matching the selector to appear. We do this with a single shared MutationObserver on the body.\n\nWhen a matching element is found, we attach a separate MutationObserver filtered to the exact attribute being mutated. If an external change happens (e.g. from a React render), we re-apply your mutation on top of the new baseline value.\n\nWhen `revert` is called, we undo the change and go back to the last externally set value. We also disconnect the element's MutationObserver to save resources.\n\n## Pausing / Resuming the Global MutationObserver\n\nWhile the library is waiting for elements to appear, it runs `document.querySelectorAll` every time a batch of elements is added or removed from the DOM.\n\nThis is performant enough in most cases, but if you want more control, you can pause and resume the global MutationObserver on demand.\n\nOne example use case is if you are making a ton of DOM changes that you know have nothing to do with the elements you are watching. You would pause right before making the changes and resume after.\n\n```ts\nimport { disconnectGlobalObserver, connectGlobalObserver } from 'dom-mutator';\n\n// Pause\ndisconnectGlobalObserver();\n\n// ... do a bunch of expensive DOM updates\n\n// Resume\nconnectGlobalObserver();\n```\n\n## Pausing and Resuming All Mutations\nWhen a mutation is added, a separate `MutationObserver` is created for it.\n\nTo ensure **all** mutations are paused, you can use the global `pauseGlobalObserver` and `resumeGlobalObserver` functions. These functions allow you to globally control mutation observation. Additionally, the `isGlobalObserverPaused` function is available to check if the global observer is currently paused.\n\n### Example Usage:\n```ts\nimport { pauseGlobalObserver, resumeGlobalObserver, isGlobalObserverPaused } from 'dom-mutator';\n\n// Pause the global observer\nif (!isGlobalObserverPaused()) {\n    pauseGlobalObserver();\n}\n\n// Make changes that would otherwise trigger mutation observers\n\n// Resume the global observer\nresumeGlobalObserver();\n```\n### Key Functions\n- `pauseGlobalObserver()`: Pauses all mutation observers globally.\n- `resumeGlobalObserver()`: Resumes all mutation observers.\n- `isGlobalObserverPaused()`: Returns true if the global observer is currently paused.\n\n## Developing\n\nBuilt with [TSDX](https://github.com/formium/tsdx).\n\n`npm start` or `yarn start` to rebuild on file change.\n\n`npm run build` or `yarn build` to bundle the package to the `dist` folder.\n\n`npm test --coverage` or `yarn test --coverage` to run the Jest test suite with coverage report.\n\n`npm run lint --fix` or `yarn lint --fix` to lint your code and autofix problems when possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrowthbook%2Fdom-mutator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrowthbook%2Fdom-mutator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrowthbook%2Fdom-mutator/lists"}