{"id":13846891,"url":"https://github.com/WebReflection/vanilla-elements","last_synced_at":"2025-07-12T08:30:51.584Z","repository":{"id":43678990,"uuid":"385220155","full_name":"WebReflection/vanilla-elements","owner":"WebReflection","description":"A Minimalistic Custom Elements Helper.","archived":false,"fork":false,"pushed_at":"2023-02-13T14:18:57.000Z","size":52,"stargazers_count":54,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-15T21:13:52.822Z","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":"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}},"created_at":"2021-07-12T11:13:24.000Z","updated_at":"2024-09-02T13:15:22.000Z","dependencies_parsed_at":"2024-01-15T20:47:29.867Z","dependency_job_id":"8df00ea7-2f60-4e04-9aed-abd78b26b428","html_url":"https://github.com/WebReflection/vanilla-elements","commit_stats":{"total_commits":51,"total_committers":1,"mean_commits":51.0,"dds":0.0,"last_synced_commit":"3cee6bda174a8e3a6b6c1237693c62b618760565"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fvanilla-elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fvanilla-elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fvanilla-elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fvanilla-elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebReflection","download_url":"https://codeload.github.com/WebReflection/vanilla-elements/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225807346,"owners_count":17527238,"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-08-04T18:00:49.604Z","updated_at":"2024-11-21T21:30:43.141Z","avatar_url":"https://github.com/WebReflection.png","language":"JavaScript","readme":"# Vanilla Elements\n\n\u003csup\u003e**Social Media Photo by [Jocelyn Morales](https://unsplash.com/@molnj) on [Unsplash](https://unsplash.com/)**\u003c/sup\u003e\n\n📣 This project didn't gain nearly nough attention as hoped so I've decided to extend builtins with [nonchalance](https://github.com/WebReflection/nonchalance#readme) and I suggest you check that out instead, as it doesn't rely at all to a *maybe* polyfill needed to work, it doesn't need to patch globals, and most importantly, it's half of the size of this module through its */runtime* variant.\n\n- - -\n\nA Minimalistic Custom Elements Helper, with optional polyfill included, compatible with every evergreen browser.\n\nThe default module export, which is ~0.5K, works natively in Chrome, Edge, and Firefox, but if you target Safari / WebKit too, you can use the `vanilla-elements/poly` variant, which is ~2K, and it includes proper features detection, leaving Chrome, Edge, and Firefox 100% native.\n\n```js\nimport {define, HTML} from 'vanilla-elements';\n\n// generic components ... or\ndefine('my-comp', class extends HTML.Element {\n  // native Custom Elements definition\n});\n\n// ... builtins extend simplified ... and\ndefine('my-div', class extends HTML.Div {\n  // native Custom Elements definition\n});\n\n// ... as decorator 🥳\n@define('my-footer')\nclass MyFooter extends HTML.Footer {}\n\ndocument.body.appendChild(new MyFooter);\n```\n\n\n## API\n\n  * the `define(name:string, Class):Class` automatically recognize the right way to define each component, either generic elements or built-ins.\n  * the `HTML` namespace contains all available HTML classes from the browser, with shortcuts such as `Div`, `Main`, `Footer`, `A`, `P`, and everything else.\n\n**[Live Example](https://codepen.io/WebReflection/pen/jOmVVQQ?editors=0010)**\n\n```js\nimport {define, HTML} from 'vanilla-elements';\nimport {render, html} from 'uhtml';\n\ndefine('h2-greetings', class extends HTML.H2 {\n  constructor() {\n    super();\n    this.html = (...args) =\u003e render(this, html(...args));\n    this.render();\n  }\n  render() {\n    this.html`Hello Vanilla Elements 👋`;\n  }\n});\n\nrender(document.body, html`\n  \u003ch2 is=\"h2-greetings\" /\u003e\n`);\n```\n\n\n## F.A.Q.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWhat is the benefit of using this module?\u003c/strong\u003e\u003c/summary\u003e\n  \u003cdiv\u003e\n\nBeside solving this [long outstanding bug](https://github.com/whatwg/html/issues/5782) out of the box, the feature detection for builtin extends is both ugly and not really Web friendly.\n\nOne could simply include [@ungap/custom-elements](https://github.com/ungap/custom-elements#readme) polyfill on top of each page and call it a day, but I wanted to have only the missing part, builtin extends, embedded in a module, and this helper is perfect for that purpose.\n\nOn top of that, I really don't like the ugly dance needed to register builtin extends, so that having a tiny utility that simplifies their definition seemed to be about right.\n\n```js\n// without this module\ncustomElements.define(\n  'my-div',\n  class extends HTMLDivElement {},\n  {extends: 'div'}\n);\n\n// with this module\nimport {define, HTML} from 'vanilla-elements';\ndefine('my-div', class extends HTML.Div {});\n```\n\nAs we can see, the definition through this module is more compact, elegant, and natural, than its native counter-part, and that's about it.\n\n  \u003c/div\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWhy isn't the polyfill included by default?\u003c/strong\u003e\u003c/summary\u003e\n  \u003cdiv\u003e\n\nThe only browser that needs a polyfill for builtin extends is Safari / WebKit, and it needs it only for builtin extends, but not everyone develops for the Web, and not everyone uses builtin extends, so the sane default is to provide a minimal utility that simplifies custom elements registration that works out of the box in every modern browser.\n\nWhenever the target needs to include Safari / WebKit, and builtin extends are used, it takes nothing to switch import from `vanilla-elements` to `vanilla-elements/poly` or use [an import-map](https://gist.github.com/WebReflection/5fc85856bba3d6eef794877fb5fa2a52) workaround to load the poly only in Safari.\n\n\n```html\n\u003c!doctype html\u003e\n\u003cscript\u003e\n(({document, chrome, netscape}) =\u003e {\n  const src = 'https://cdn.skypack.dev/vanilla-elements/';\n  const {head} = document;\n  const script = head.insertBefore(document.createElement('script'), head.firstChild);\n  script.type = 'importmap';\n  script.textContent = JSON.stringify({\n    imports: {\n      'vanilla-elements': (chrome || netscape) ? src : (src + 'es.js')\n    }\n  });\n})(self);\n\u003c/script\u003e\n```\n\n  \u003c/div\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWhat are the exports?\u003c/strong\u003e\u003c/summary\u003e\n  \u003cdiv\u003e\n\nFor development usage, through bundlers and similar tools:\n\n  * `vanilla-elements` points at the [main.js](./esm/main.js), and it doesn't include the polyfill\n  * `vanilla-elements/poly` points at the generated [index.js](./index.js) file, and include the polyfill after feature detection\n\nFor CDN usage in the wild:\n\n  * the `//unpkg.com/vanilla-elements` CDN points at the minified [es.js](./es.js) which *includes* the polyfill (it's the minified index)\n  * for `skypack.dev` minified file, you can point at the `es.js` file directly: [//cdn.skypack.dev/vanilla-elements/es.js](https://cdn.skypack.dev/vanilla-elements/es.js)\n\n  \u003c/div\u003e\n\u003c/details\u003e\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebReflection%2Fvanilla-elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebReflection%2Fvanilla-elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebReflection%2Fvanilla-elements/lists"}