Create Custom HTML Element

A powerful tool for building a scalable, reusable, fast, and lightweight UI Component Library for any web technologies, powered by Custom Elements.

Table Of Content

Features
Quick Start
First Element
Decorators
Utilities
JSX
Lifecycles
Bundlers
Transformer

Features

Plugin-Based: Facilitates the seamless development of diverse plugins and the customization of outputs to meet specific requirements
Built-In Plugins: Provides a variety of plugins that cater to different requirements.
Global Config: Provides the ability to define global configs for all elements.
Typings: Creates TypeScript types for seamless element usage across different environments.
TypeScript + JSX: Using two powerful tools, TypeScript and JSX, to create elements.
Built-In Utilities: Provides a set of JavaScript utility functions used across multiple elements.
Secure: Restricts unwanted access to internal properties and methods.
Style File Recognition: Identifies and links the relevant style file to the element.
Tag Name Recognition: Generates tag name from the class name.
Clean Syntax: Uses a minimal amount of code to achieve the same functionality, making the code easier to read, understand, and maintain.

Quick Start

Before proceeding, ensure you have the latest LTS version of Node.js installed on your system.

1- Create a new project

npm init @htmlplus/element@latest

2- Navigate to the project directory

cd htmlplus-project

3- Install the dependencies

npm i

4- Start the project

npm start

First Element

An example demonstrating the implementation and usage of an element.

Each element is stored in a file such as my-counter.tsx.

import { Element, State } from '@htmlplus/element';

@Element()
export class MyCounter {
  @State()
  value: number = 0;

  render() {
    return (
      <host onClick={() => this.value++}>
        Count is {this.value}
      </host>
    )
  }
}

The element's style is stored in a file such as my-counter.css, which shares the same name as the element file my-counter.tsx.

:host {
  display: inline-block;
  border: 1px solid black;
  color: black;
  padding: 1em;
  cursor: pointer;
}

To execute the element, include it in the index.html file.

<body>
  <my-counter></my-counter>
</body>

Decorators

Decorators can greatly enhance code maintainability, improving efficiency, readability, and reusability.

Bind

Used to bind a method of a class to the current context, making it easier to reference this within the method.

In the my-counter.tsx file.

import { Bind, Element, State } from '@htmlplus/element';

@Element()
export class MyCounter {
  @State()
  value: number = 0;

  @Bind()
  onClick() {
    this.value++;
  }

  render() {
    return (
      <host onClick={this.onClick}>
        Count is {this.value}
      </host>
    )
  }
}

In the index.html file.

<my-counter></my-counter>

Consumer

TODO

Direction

Indicates whether the Direction of the element is Right-To-Left or Left-To-Right.

In the my-element.tsx file.

import { Direction, Element } from '@htmlplus/element';

@Element()
export class MyElement {
  @Direction()
  direction!: 'ltr' | 'rtl';

  render()  {
    return (
      <div>
        The direction of the element is
        <u>
          {this.direction}
        </u>
      </div>
    )
  }
}

In the index.html file.

<body dir="rtl">
  <my-element></my-element>
</body>

Element

The class marked with this decorator is considered a Custom Element, and its name, in kebab-case, serves as the element name.

It is important to note that each file can only contain one class with this condition.

In the say-hello.tsx file.

import { Element } from '@htmlplus/element';

@Element()
export class SayHello {
  render() {
    return <div>Hello World</div>
  }
}

In the index.html file.

<say-hello></say-hello>

Event

Provides the capability to dispatch a CustomEvent from an element.

Parameters:

options (Optional)
An object that configures options for the event dispatcher.
- bubbles (Optional)
  A boolean value indicating whether the event bubbles. The default is false.
- cancelable (Optional)
  A boolean value indicating whether the event can be cancelled. The default is false.
- composed (Optional)
  A boolean value indicating whether the event will trigger listeners outside of a shadow root (see Event.composed for more details). The default is false.

In the my-button.tsx file.

import { Element, Event, EventEmitter } from '@htmlplus/element';

@Element()
export class MyButton {
  @Event()
  myClick!: EventEmitter<string>;

  render() {
    return (
      <button onClick={() => this.myClick("It's a message form MyButton!")}>
        <slot />
      </button>
    )
  }
}

In the index.html file.

<my-button id="button">Button</my-button>

<script>
  document
    .getElementById('button')
    .addEventListener('my-click', (event) => {
      alert(event.detail);
    });
</script>

Host

Indicates the host of the element.

In the my-element.tsx file.

import { Element, Host } from '@htmlplus/element';

@Element()
export class MyElement {
  @Host()
  host!: HTMLElement;

  get isSame() {
    return this.host == document.querySelector('my-element');
  }

  connectedCallback() {
    console.log('Is Same: ' + this.isSame);
  }
}

In the index.html file.

<my-element></my-element>

IsRTL

Indicates whether the direction of the element is Right-To-Left or not.

In the my-element.tsx file.

import { Element, IsRTL } from '@htmlplus/element';

@Element()
export class MyElement {
  @IsRTL()
  isRTL!: boolean;

  render()  {
    return (
      <div>
        The direction of the element is
        <u>
          {this.isRTL ? 'rtl' : 'ltr'}
        </u>
      </div>
    )
  }
}

In the index.html file.

<body dir="rtl">
  <my-element></my-element>
</body>

Listen

Will be called whenever the specified event is delivered to the target More.

Parameters:

type (Required)
A case-sensitive string representing the Event Type to listen for.
options (Optional)
An object that configures options for the event listener.
- capture (Optional)
  A boolean value indicating that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree. If not specified, defaults to false.
- once (Optional)
  A boolean value indicating that the listener should be invoked at most once after being added. If true, the listener would be automatically removed when invoked. If not specified, defaults to false.
- passive (Optional)
  A boolean value that, if true, indicates that the function specified by listener will never call preventDefault(). If a passive listener does call preventDefault(), the user agent will do nothing other than generate a console warning.
- signal (Optional)
  An AbortSignal. The listener will be removed when the given AbortSignal object's abort() method is called. If not specified, no AbortSignal is associated with the listener.
- target (Optional)
  The target element, defaults to host.

In the my-button.tsx file.

import { Element, Listen } from '@htmlplus/element';

@Element()
export class MyButton {
  @Listen('click')
  onClick(event) {
    alert('The my-button was clicked!');
  }

  render() {
    return <slot />
  }
}

In the index.html file.

<my-button>Click Me</my-button>

Method

Provides a way to encapsulate functionality within an element and invoke it as needed, both internally and externally.

In the my-counter.tsx file.

import { Element, Method, State } from '@htmlplus/element';

@Element()
export class MyCounter {
  @State()
  value: number = 0;

  @Method()
  increase() {
    this.value++;
  }

  render() {
    return (
      <host>
        Count is {this.value}
      </host>
    )
  }
}

In the index.html file.

<my-counter id="counter"></my-counter>

<script>
  setInterval(() => {
    document.getElementById('counter').increase();
  }, 1000);
</script>

Property

Creates a reactive property, reflecting a corresponding attribute value, and updates the element when the property is set.

Parameters:

options (Optional)
The configuration for property decorator.
- attribute (Optional)
  Specifies the name of the attribute related to the property.
- reflect (Optional)
  Whether property value is reflected back to the associated attribute. default is false.
- type (Optional)
  Specifies the property type and supports data types. If this value is not set, it will be set automatically during transforming.

In the say-greeting.tsx file.

import { Element, Property } from '@htmlplus/element';

@Element()
export class SayGreeting {
  @Property()
  name?: string = 'Simon';

  render() {
    return <div>Hi {this.name}</div>
  }
}

In the index.html file.

<say-greeting name="Jan"></say-greeting>

Provider

TODO

Query

Selects the first element in the shadow dom that matches a specified CSS selector.

Parameters:

selectors (Required)
A string containing one or more selectors to match. This string must be a valid CSS selector string; if it isn't, a SyntaxError exception is thrown. See Locating DOM elements using selectors for more about selectors and how to manage them.

In the my-button.tsx file.

import { Element, Query } from '@htmlplus/element';

@Element()
export class MyButton {
  @Query('.btn')
  buttonRef!: HTMLButtonElement;

  loadedCallback() {
    console.log(this.buttonRef); // <button class="btn"></button>
  }

  render() {
    return (
      <button class="btn">
        <slot />
      </button>
    )
  }
}

In the index.html file.

<my-button>
  Button
</my-button>

QueryAll

Selects all elements in the shadow dom that match a specified CSS selector.

Parameters:

selectors (Required)
A string containing one or more selectors to match against. This string must be a valid CSS selector string; if it's not, a SyntaxError exception is thrown. See Locating DOM elements using selectors for more information about using selectors to identify elements. Multiple selectors may be specified by separating them using commas.

In the my-button.tsx file.

import { Element, QueryAll } from '@htmlplus/element';

@Element()
export class MyButton {
  @QueryAll('span')
  spanRefs!: NodeList;

  loadedCallback() {
    console.log(this.spanRefs); // [span, span]
  }

  render() {
    return (
      <button>
        <span> Suffix </span>
        <b>
          <slot />
        </b>
        <span> Prefix </span>
      </button>
    )
  }
}

In the index.html file.

<my-button>
  Button
</my-button>

Slots

Returns the slots name.

In the my-element.tsx file.

import { Element, Slots } from '@htmlplus/element';

@Element()
export class MyElement {
  @Slots()
  slots;

  connectedCallback() {
    console.log(this.slots); // {header: true, default: true, footer: true}
  }

  render() {
    return (
      <host>
        <slot name="header"></slot>
        <slot></slot>
        <slot name="footer"></slot>
      </host>
    )
  }
}

In the index.html file.

<my-element>
  <div slot="header">HEADER</div>
  <div>BODY</div>
  <div slot="footer">FOOTER</div>
</my-element>

State

Applying this decorator to any class property will trigger the element to re-render upon the desired property changes.

In the my-button.tsx file.

import { Element, State } from '@htmlplus/element';

@Element()
export class MyButton {
  @State()
  active?: boolean;

  toggle() {
    this.active = !this.active;
  }

  render() {
    return (
      <button onClick={() => this.toggle()}>
        Click To Change The Status ({this.active ? 'On' : 'Off'})
      </button>
    )
  }
}

In the index.html file.

<my-button></my-button>

Watch

Monitors @Property() and @State() to detect changes. The decorated method will be called after any changes, with the key, newValue, and oldValue as parameters. If the key is not defined, all @Property() and @State() are considered.

Parameters:

keys (Optional)
Collection of @Property() and @State() names.
immediate (Optional)
Triggers the callback immediately after initialization.

In the my-element.tsx file.

import { Element, Property, Watch } from '@htmlplus/element';

@Element()
export class MyElement {
  @Property()
  value?: string;

  @Watch('value')
  watcher(key, newValue, oldValue) {
    console.log(key, newValue, oldValue);
  }
}

In the index.html file.

<my-element id="element"></my-element>

<script>
  setInterval(() => {
    document.getElementById('element').value = new Date();
  }, 1000);
</script>

Utilities

Utilities are a versatile tool in element building projects, eliminating the need for rewriting.

classes

TODO

getConfig

TODO

setConfig

TODO

direction

Indicates whether the Direction of the element is Right-To-Left or Left-To-Right.

TODO

dispatch

TODO

host

Indicates the host of the element.

TODO

isCSSColor

Determines whether the given input string is a valid CSS Color or not.

TODO

isCSSColor('red')                       // true
isCSSColor('#ff0000')                   // true
isCSSColor('#ff000080')                 // true
isCSSColor('rgb(255, 0, 0)')            // true
isCSSColor('rgba(255, 0, 0, 0.3)')      // true
isCSSColor('hsl(120, 100%, 50%)')       // true
isCSSColor('hsla(120, 100%, 50%, 0.3)') // true
isCSSColor('invalid color')             // false

isRTL

Indicates whether the direction of the element is Right-To-Left or not.

TODO

on

TODO

off

TODO

query

Selects the first element in the shadow dom that matches a specified CSS selector.

TODO

queryAll

Selects all elements in the shadow dom that match a specified CSS selector.

TODO

slots

Returns the slots name.

TODO

toUnit

Converts a value to a unit.

TODO

JSX

TODO

host

TODO

part

TODO

Lifecycles

Elements encompass several lifecycle methods, each triggered at different stages in the element's life cycle, enabling developers to control the element's behavior and perform customized actions.

adoptedCallback

TODO

connectedCallback

A lifecycle callback method that is called each time the element is added to the document.

import { Element } from '@htmlplus/element';

@Element()
export class MyElement {
  connectedCallback() {
    console.log('Element is connected!');
  }
}

disconnectedCallback

TODO

import { Element } from '@htmlplus/element';

@Element()
export class MyElement {
  disconnectedCallback() {
    console.log('Element is disconnected!');
  }
}

loadedCallback

TODO

import { Element } from '@htmlplus/element';

@Element()
export class MyElement {
  loadedCallback() {
    console.log('Element is loaded!');
  }
}

updateCallback

TODO

updatedCallback

TODO

Bundlers

TODO

Rollup

TODO

Vite

TODO

Transformer

TODO

Getting Started

TODO

import { TransformerPlugin, transformer } from '@htmlplus/element';
import {
  customElement,
  extract,
  parse,
  read,
  style,
  validate,
} from '@htmlplus/element/transformer.js';

const plugins = [
  read(),
  parse(),
  validate(),
  extract(),
  style(),
  customElement()
];

const { start, run, finish } = transformer(...plugins);

await start();

const context1 = await run('/my-avatar.tsx');
const context2 = await run('/my-button.tsx');
const context3 = await run('/my-switch.tsx');

await finish();

Plugins

TODO

import {
  assets,
  copy,
  customElement,
  document,
  extract,
  parse,
  read,
  readme,
  style,
  validate,
  visualStudioCode,
  webTypes
} from '@htmlplus/element/transformer.js';

Name		Name	Last commit message	Last commit date
Latest commit History 437 Commits
.github		.github
.vscode		.vscode
development		development
dist		dist
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.releaserc		.releaserc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Create Custom HTML Element

Table Of Content

Features

Quick Start

First Element

Decorators

Utilities

JSX

Lifecycles

Bundlers

Transformer

About

Releases 40

Packages

Contributors 4

Languages

License

htmlplus/element

Folders and files

Latest commit

History

Repository files navigation

Create Custom HTML Element

Table Of Content

Features

Quick Start

First Element

Decorators

Utilities

JSX

Lifecycles

Bundlers

Transformer

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 40

Packages 0

Contributors 4

Languages

Packages