https://github.com/leifriksheim/customel
🔹 A tiny helper function for creating Web Components
https://github.com/leifriksheim/customel
custom-elements-v1 tagged-template-literals ui-library webcomponents
Last synced: 24 days ago
JSON representation
🔹 A tiny helper function for creating Web Components
- Host: GitHub
- URL: https://github.com/leifriksheim/customel
- Owner: leifriksheim
- License: mit
- Created: 2019-02-25T22:28:53.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T17:20:55.000Z (almost 3 years ago)
- Last Synced: 2025-09-12T07:02:36.523Z (24 days ago)
- Topics: custom-elements-v1, tagged-template-literals, ui-library, webcomponents
- Language: JavaScript
- Homepage:
- Size: 1.03 MB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> A tiny helper function for creating Web Components
## Highlights
- Zero dependencies, [only 2kb](https://bundlephobia.com/result?p=customel@latest) 🕊️
- Template literals as templating engine 💡
- Write standards-compliant Web Components 🌍
- Use with Vue, React, Angular and friends 🤝
- Small and easy API 🚴
## Table of contents
* [Installation](#installation)
* [Introduction](#introduction)
* [Getting started](#getting-started)
* [Documentation](#documentation)
* [Template](#template)
* [Styles](#styles)
* [State](#state)
* [Props](#props)
* [Actions](#actions)
## Installation
CDN
Create an index.html file and include Customel with the CDN:
```html
```
If you are using native ES Modules, you can include it in the index.html like this:
```html
import customel from "//unpkg.com/customel?module";
```
NPM
```
npm install customel
```
```js
import customel from "customel";
```
## Introduction
Custom elements are awesome. They make it possible for everybody to use your components, no matter which new javascript framework they are using. As a part of the native web platform they are a great way to build maintainable and long lasting UI-libraries.
Still, writing Web Components from scratch can require quite a lot of boiler plate. Customel is a small wrapper around the `HTMLElement` class that reduces a lot of the boiler plate, enforces some best practises, and makes it easier to make new custom elements.
Customel is not meant to be a way to build software or large applications. It is built as a way to create small, reusable Web Components.
## Getting started
The easiest way to try out Customel is using the [JSFiddle Hello World example](https://jsfiddle.net/waysofperception/mL9nopdf/). You can follow the Quick Start from here.
First create a file called `my-element.js`. Import Customel, create your component, and define it.
```js
// my-element.js
import customel from "//unpkg.com/customel?module";
const Element = {
template() {
return "
Hello my new element!";
}
};
customElements.define("my-element", customel(Element));
```
Create a `index.html` file, and import `my-element.js`.
Your custom element is now ready to be used!
```html
```
## Documentation
### Template
You probably want to render some html inside your custom element.
The easiest way to do this is to just return a string with some HTML:
```js
const Element = {
template() {
return "
HTML as a string";
}
};
```
The `template` function also provides a template literal called `html` that we can use when we want to add event handlers to the component, or we want to loop through a list.
```js
const items = ["Item 1", "Item 2"];
const Element = {
template: function(html) {
return html`
alert("Clicked")}>Button
- ${item}
${items.map(
item =>
html`
`
)}
`;
}
};
```
### Styles
To apply styles to your custom element, you can return CSS as a string:
```js
const Element = {
styles() {
return `
button {
background-color: red;
color: white;
}
`;
},
template: function(html) {
return html`
My button
`;
}
};
```
You can also use props or state to render styles conditionally.
```js
const Element = {
props: {
active: false
},
styles() {
return `
button {
background-color: ${this.props.active ? "red" : "blue"};
color: white;
}
`;
},
template: function(html) {
return html`
My button
`;
}
};
```
This will however cause a rerender of the whole internal stylesheet of the component. So it is adviced to toggle classes based on props or state instead:
```js
const Element = {
props: {
active: false
},
styles() {
return `
button {
background-color: blue;
color: white;
}
button.active {
background-color: red;
}
`;
},
template: function(html) {
const buttonClass = this.props.active ? "active" : null;
return html`
My button
`;
}
};
```
### State
Your state is contained in a state object.
You can modify the state with the `this.setSate` function.
`this.setState` will cause a rerender and you will get a fresh DOM with updated data.
```js
const Element = {
state: {
active: false
},
template: function(html) {
return html`
this.setState({ active: true })}>
Active state is ${this.state.active}
`;
}
};
```
### Props
Use props to define data that your custom element can recieve from the outside.
Always provide a default value to your props.
#### Simple props
If the default value is a `string`, `number` or a `boolean` then your prop will be available as an attribute on your custom element:
```js
const Accordion = {
props: {
open: false
},
template: function(html) {
return html`
Accordion title
${this.props.open
? html`
Accordion content
`
: null}
`;
}
};
customElement.define("my-accordion", customel(Accordion));
```
This makes attributes available on your component.
```html
const accordion = document.querySelector('my-accordion');
accordion.addEventListener("click" => {
if (accordion.hasAttribute("open")) {
accordion.removeAttribute("open");
} else {
accordion.setAttribute("open", "");
}
})
```
They will also be reflected as properties, so you could just do this as well:
```html
const accordion = document.querySelector("my-accordion");
accordion.open = !accordion.open;
```
#### Advanced props
If the default value is a `function`, `object`, `array` or any other type of data, it will be available as a property on the element instead of an attribute.
```js
const List = {
props: {
todos: ["Buy milk", "Learn stuff"]
},
template: function(html) {
return html`
- ${todo}
${this.props.todos.map(
todo => html`
`
)}
`;
}
};
customElement.define("my-list", customel(List));
```
```html
// "todos" is an array and can only be updated to properties on the element
// setting the property will triggger a rerender of the component, just like setting a new attribute
document.querySelector("my-list").todos = ["Other things", "More things"];
```
### Actions
```js
const Element = {
props: {
title: "Title"
},
actions: {
showMessage() {
alert("Title: is" + this.title);
}
},
template: function(html) {
return html`
this.actions.showMessage()}>
My button
`;
}
};
```
## Use in frameworks
### React
### Vue
Custom Elements play nicely with Vue, but for rich data you will need to add a `.prop` on the attribute to bind the value to the property and not the attribute of the custom element.
For now you will also need to replace the whole array every time you update it's value, as Customel does not watch for nested changes. This may come in the future via use of a Proxy.
```html
new Vue({
el: "#vue",
data: {
mainTitle: "My accordion",
items: [
{
title: "My title",
content: "Here is some content about this stuff"
},
{
title: "Another title",
content: "Here is some other content about this stuff"
}
]
}
});
```
### Angular
Coming...
### React
Coming...
Customel is [MIT licensed](./LICENSE).