custom-elements-ts

Create native custom elements using Typescript without using any third party libraries.

npm install custom-elements-ts

Usage

import { CustomElement } from 'custom-elements-ts';

@CustomElement({
  tag: 'counter-element',
  templateUrl: 'counter-element.html',
  styleUrl: 'counter-element.scss'
})
export class CounterElement extends HTMLElement {
  // code as you would when creating a native HTMLElement
  // full source code is at demo/counter
}

<!--index.html-->
<counter-element></counter-element>
<script src="counter.umd.js"></script>

Decorators

Decorator	Target	Parameters	Description
@Prop()	property	-	custom attribute/properties, reflects primitive properties to attributes
@Toggle()	property	-	boolean attribute/properties, it is based on the presence of the attribute but also works with "true" and "false"
@Dispatch()	property	(event?)	used to declare a CustomEvent which you could dispatch using the `.emit` method of its type `DispatchEmitter`. The `event` parameter is used to set the name of the `CustomEvent`
@Watch()	method	(property)	triggers the method when a `property` is changed
@Listen()	method	(event, selector?)	listens to an `event` on the `host` element or on the `selector` if specified

@Prop()

import { CustomElement, Prop } from 'custom-elements-ts';

@CustomElement({
  tag: 'todo-list',
  ...
})
export class TodoList extends HTMLElement {
  @Prop() color: string;
  @Prop() list: TodoItem[];
}

Since color is a primitive type of string it can be accessed via attributes and properties

const element = document.querySelector('todo-list');
// accessing value via attribute
const attrValue = element.getAttribute('color');
// setting value via attribute
element.setAttribute('color', 'red');
 
// accessing value via property
const propertyValue = element.color;
// setting via property
element.color = 'red';

On the other hand list is a rich data type (objects or arrays) can only be accessed/set via property

@Toggle()

Toggle attributes work the same way as HTML boolean attributes as defined by W3C for the most part. We changed a few things to overcome confusion. Check the table below for reference:

Markup	`disabled`	Description
`<c-input />`	false	Follows W3C standard
`<c-input disabled/>`	true	Follows W3C standard
`<c-input disabled="true"/>`	true	Follows W3C standard
`<c-input disabled="asd"/>`	false	`false` since `asd` does not evaluate to a valid boolean
`<c-input disabled="false"/>`	false	`false` since the boolean `false` converted to a string is `"false"`
`<c-input disabled="true"/>`	true	`true` since the boolean `true` converted to a string is `"true"`

@Dispatch()

Creating a custom event

import { CustomElement, Dispatch, DispatchEmitter } from 'custom-elements-ts';

...
export class TodoList extends HTMLElement {
  // Creating a CustomEvent
  // custom event name will be `on.change`
  @Dispatch() onChange: DispatchEmitter;

  // Creating a CustomEvent with custom name `ce.select` 
  @Dispatch('ce.select') onSelect: DispatchEmitter;
}

Triggering the custom event from the example above:

  triggerOnChange() {
    // adding more data to the event object
    this.onChange.emit({detail: 'event changed'});
    this.onSelect.emit({detail: 'select triggered'});
  }

@Watch()

import { CustomElement, Dispatch, Prop } from 'custom-elements-ts';

...
export class TodoList extends HTMLElement {
  @Prop() color: string;

  @Watch('color')
  colorChanged() {
    // trigger when color property color changes
    // either via property or attribute
  }
}

@Listen()

Listen has parameters event and selector. Event is any valid javascript event. Selector is anything that works with querySelector()

import { CustomElement, Dispatch, Prop } from 'custom-elements-ts';

...
export class TodoList extends HTMLElement {
  @Listen('click')
  elementClicked() {
    // triggers when the element is clicked
  }

  @Listen('click','a')
  anchorClicked() {
    // triggers when an `a` inside the element is clicked
  }
}

Setup

Running the demos

npm start <element-name>

Building the demo

npm run build <element-name>

If you want to create a minified bundle

npm run build -- <element-name> --prod

dev-marlon/custom-elements-ts