elements-x/core

The simplest custom element library for building fast, lightweight, and reusable tags.

Simple It's tiny(5KB gzipped) wrapper of Custom Elements. With minimum coding, you can create your own custom elements in minutes.

Custom Element The return from customElement() is a HTMLElement. Thus, it works anywhere you use HTML, with any framework or none at all.

Library All you need to know is a function customElement(options). options is just a HTMLElement class expression, which you know it already. e.g., connectedCallback(), attributeChangedCallback(), etc.

Getting Started

@elements-x is available as the @elements-x/core package via npm.

$ npm i @elements-x/core

Then import into JavaScript or TypeScript files: Now you can use the custom element in any HTML, with any framework or none at all.

customElement() returns a HTMLElement class and defines a custom element. You can think of it as a HTML tag, which reacts to attribute change, property change, and fires events.

import { customElement } from '@elements-x/core';

customElement('hello-custom-element', {
  html: '<h1>{{hello}} {{world}}</h1>',
  css:  'hello-custom-element { color: red; }',
  attrs : {
    hello: 'Hello',
    world: 'Custom Element'
  }
});

API

customElement(tagName:string, options: Options) : HTMLElement

interface Options {
  // Initialize required condition e.g. JQuery library, connectedCallback() will wait until it is resolved.
  await?: () => Promise<any>; 
  
  // Customized built-in elements
  extends?: string; 

  // the attribute names will be registered to observedAttributes, 
  // so that anytime when the attribute  value changes, `attributeChangedCallback()`will be executed.
  attrs?: { [key: string]: AttrValue};
  
  // property is set to this._props. Anytime when a property value changes, 
  // `propsChangedCallback()` will be executed.
  props?: { [key: string]: any };
  
  // Compiles HTML using Mustache. attrs and props are passed as context to compile new HTML
  html?: string;
  
  // Adds <style id="<<tagName</code>>"> only once when connected.
  css?: string; 
  
  // Add event listeners to this element. 
  // By defining `events` keys and values, you are ready to listen to any events.
  events?: { [key: string]: Function}; 
  
  // called after `connectedCallback()`. You also can call it to re-render 
  // html from `attributeChannged()` and `propsChangedCallback()`.
  render?: Function; 
  
  debug?: boolean; // prints debug messages
  constructorCallback?: Function;
  connectedCallback?: Function; // element is added to the document
  disconnectedCallback?: Function; // element is removed to the document
  adoptedCallback?: Function; // element is transferred to a new document
  attributeChangedCallback?: Function; // Invoked when attribute is changed
  propsChangedCallback?: Function; // Invoked when a prop is changed
}

TODO: support custom built-in for Safari browser

• https://www.sobyte.net/post/2021-08/safari-buildin-custom-element-polyfill/#:~:text=Safari%20browser%20does%20not%20support%20build-in%20custom%20elements%2C,supports%20the%20following%20HTML-formatted%20UI%20components%20by%20default.
• https://github.com/WebReflection/custom-elements-builtin
• https://unpkg.com/@webreflection/custom-elements-builtin