{"id":20513647,"url":"https://github.com/webreflection/custom-elements","last_synced_at":"2025-04-13T23:57:55.291Z","repository":{"id":45666293,"uuid":"285578327","full_name":"WebReflection/custom-elements","owner":"WebReflection","description":"An unobtrusive customElements V1 polyfill","archived":false,"fork":false,"pushed_at":"2023-06-21T07:57:29.000Z","size":4046,"stargazers_count":33,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T23:57:47.570Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://medium.com/@WebReflection/some-custom-elements-update-376317dd7862","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebReflection.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}},"created_at":"2020-08-06T13:26:08.000Z","updated_at":"2025-02-22T04:56:16.000Z","dependencies_parsed_at":"2024-03-02T23:33:53.757Z","dependency_job_id":"d2e56cc1-0eca-46c4-bfe8-d13596ab5a77","html_url":"https://github.com/WebReflection/custom-elements","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fcustom-elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fcustom-elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fcustom-elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fcustom-elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebReflection","download_url":"https://codeload.github.com/WebReflection/custom-elements/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248799928,"owners_count":21163403,"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-11-15T21:12:22.895Z","updated_at":"2025-04-13T23:57:55.260Z","avatar_url":"https://github.com/WebReflection.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Custom Elements V1 Polyfill\n\n\u003csup\u003e**Social Media Photo by [Joanna Kosinska](https://unsplash.com/@joannakosinska) on [Unsplash](https://unsplash.com/)**\u003c/sup\u003e\n\nAn unobtrusive customElements V1 polyfill.\n\n## Warning: [@ungap/custom-elements](https://github.com/ungap/custom-elements#readme) is what you are looking for!\n\nThis module is a *ponyfill* but the official module for CE is not here.\n\nUse this module **only** if you understand what a *ponyfill* here, and only if you are capable of not invoking this more than once in your project.\n\n- - -\n\n## Compatibility\n\nThe polyfill gracefully enhances the following minimum versions of at least these browsers, up to their latest version:\n\n  * Chrome 38\n  * Firefox 14\n  * Opera 25\n  * Internet Explorer 11 and Edge 12\n  * Safari 8 and WebKit based\n  * Samsung Internet 3\n\n\n## How To Polyfill\n\nThis polyfill provides both global fixes and ESM or CJS modules.\n\n\n### As global polyfill\n\nThe [index.js](./index.js) and its [min.js](./min.js) versions are dedicated for usage within _HTML_ pages.\n\n```html\n\u003c!-- simply include this script on top of your HTML files --\u003e\n\u003cscript src=\"//unpkg.com/@webreflection/custom-elements\"\u003e\u003c/script\u003e\n```\n\nPatches are applied after feature detections to bring `customElements` V1 to legacy browsers, as well as modern browsers that are not fully specs compliant (i.e. Safari / WebKit).\n\n\n### As ESM\n\nThe [esm/index.js](./esm/index.js) is the default export. The module does not patch anything until explicitly invoked.\n\n```js\nimport cePolyfill from '@webreflection/custom-elements';\nconst customElements = cePolyfill(self || window || global);\nconst {define, get, whenDefined} = customElements;\n```\n\n\n### As CJS\n\nEverything said for _ESM_, except the file is in [cjs/index.js](./cjs/index.js).\n\n```js\nconst cePolyfill = require('@webreflection/custom-elements');\nconst customElements = cePolyfill(self || window || global);\nconst {define, get, whenDefined} = customElements;\n```\n\n\n#### Extra note about ESM/CJS modules\n\nIf you'd like to *not* pollute the global object with all the patches, you need to pass an object that contains all needed globals.\n\nHowever, this is strongly discouraged unless you are doing this to test/cover something via node.js only, not browsers.\n\n**Example**\n```js\nconst customElements = cePolyfill({\n  // pass a bound version of customElements if available\n  customElements: self.customElements \u0026\u0026 {\n    // only define and get are needed\n    define: customElements.define.bind(customElements),\n    get: customElements.get.bind(customElements)\n  },\n\n  // needed globals through this `self` namespace\n  Map, MutationObserver, Object, Set, WeakMap,\n  HTMLElement, Error, TypeError,\n\n  // the `document.createElement` might be patched regardless\n  document,\n  // the `Element.prototype.attachShadow` might be patched regardless\n  Element,\n  // the `Node.prototype.isConnected` might be patched regardless\n  Node,\n\n  // one or more globals you'd like to ake available for builtin extends\n  HTMLButtonElement,\n  HTMLDivElement,\n});\n```\n\n\n## To Keep In Mind\n\nThis is *not* a _ShadowDOM_ polyfill, this is just the current [Custom Elements V1 as specified by standard bodies](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-api).\n\nIf you are looking for a reasonable attempt to polyfill _ShadowDOM_ too, [ShadyDOM](https://github.com/webcomponents/polyfills/tree/master/packages/shadydom#readme) would be my recommendation.\n\nPlease note, once this polyfill has been tested enough it will be moved to under [@ungap](https://github.com/ungap/).\n\nPlease also note that:\n\n  * to polyfill _customElements_ without builtin extends use [custom-elements-no-builtin](https://github.com/WebReflection/custom-elements-no-builtin#readme) instead\n  * for even more legacy browsers, ditch this module and use [document-register-element](https://github.com/WebReflection/document-register-element#readme) instead, but bear in mind this older version has its own legacy caveats\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Fcustom-elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebreflection%2Fcustom-elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Fcustom-elements/lists"}