https://github.com/geocine/custom-elements-ts
Create native custom elements using Typescript
https://github.com/geocine/custom-elements-ts
custom-elements decorators shadow-dom typescript web-components
Last synced: 7 months ago
JSON representation
Create native custom elements using Typescript
- Host: GitHub
- URL: https://github.com/geocine/custom-elements-ts
- Owner: geocine
- Created: 2018-07-08T02:49:11.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-04-24T23:15:18.000Z (over 5 years ago)
- Last Synced: 2025-02-27T08:54:13.467Z (7 months ago)
- Topics: custom-elements, decorators, shadow-dom, typescript, web-components
- Language: TypeScript
- Homepage: https://geocine.github.io/custom-elements-ts/
- Size: 846 KB
- Stars: 62
- Watchers: 8
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# custom-elements-ts
[](https://coveralls.io/github/geocine/custom-elements-ts?branch=master)
[](https://travis-ci.org/geocine/custom-elements-ts)
[](https://www.npmjs.com/package/custom-elements-ts)
[](https://opensource.org/licenses/MIT)
Create native custom elements using Typescript without using any third party libraries.
```
npm install custom-elements-ts
```
## Usage
```ts
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
}
```
```html
```
## 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()
```ts
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
```ts
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](http://www.w3.org/TR/2008/WD-html5-20080610/semantics.html#boolean) for the most part. We changed a few things to overcome confusion. Check the table below for reference:
| Markup | `disabled` | Description |
|-------------------------------|------------|----------------------------------------------------------------------|
| `` | false | Follows W3C standard |
| `` | true | Follows W3C standard |
| `` | true | Follows W3C standard |
| `` | false | `false` since `asd` does not evaluate to a valid boolean |
| `` | false | `false` since the boolean `false` converted to a string is `"false"` |
| `` | true | `true` since the boolean `true` converted to a string is `"true"` |
### @Dispatch()
**Creating a custom event**
```ts
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:
```ts
triggerOnChange() {
// adding more data to the event object
this.onChange.emit({detail: 'event changed'});
this.onSelect.emit({detail: 'select triggered'});
}
```
### @Watch()
```ts
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()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)
```ts
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
```
### Building the demo
```
npm run build
```
If you want to create a minified bundle
```
npm run build -- --prod
```