ayo/wcb

Web Components in Easy Mode https://webcomponent.io

Find a file

Ayo 7500f0c3fe chore: bump version for release		2023-12-08 22:13:51 +01:00
.vscode	feat(site): initial content	2023-11-22 10:45:23 +01:00
assets	chore: update examples	2023-09-16 23:08:52 +02:00
examples	feat: templating (#9 )	2023-12-08 21:31:05 +01:00
site	feat(site): update code example import	2023-12-08 15:35:42 +01:00
src	fix: wrong previous dom used in diffing	2023-12-08 22:13:34 +01:00
.gitignore	feat(site): initial website for webcomponent.io	2023-11-22 08:55:10 +01:00
LICENSE	chore: add LICENSE file	2023-11-10 21:56:12 +01:00
package-lock.json	2.0.0	2023-12-01 09:11:18 +01:00
package.json	chore: bump version for release	2023-12-08 22:13:51 +01:00
prepare.js	don't ship devDependencies	2023-11-21 13:32:10 +01:00
README.md	chore: update readme; props can now hold object	2023-12-07 18:31:57 +01:00
sample.html	feat: support objects in props	2023-12-07 17:30:53 +01:00
tsconfig.json	chore: export all utils	2023-12-08 15:05:27 +01:00

README.md

Web Component Base

A zero-dependency, ~600 Bytes (minified & gzipped), JS base class for creating reactive custom elements easily

When you extend the WebComponent class for your component, you only have to define the template and properties. Any change in any property value will automatically cause just the component UI to render.

The result is a reactive UI on property changes. View on CodePen ↗

Table of Contents

Import via unpkg
Installation via npm
Usage
`template` vs `render()`
Prop access
1. Alternatives
Quick Start Example
Life-Cycle Hooks
1. `onInit` - the component is connected to the DOM, before view is initialized
2. `afterViewInit` - after the view is first initialized
3. `onDestroy` - the component is disconnected from the DOM
4. `onChanges` - every time an attribute value changes
Library Size

Import via unpkg

Import using unpkg in your vanilla JS component. We will use this in the rest of our usage examples.

import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

Installation via npm

Usable for projects with bundlers or using import maps.

npm i web-component-base

Usage

In your component class:

// HelloWorld.mjs
import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

class HelloWorld extends WebComponent {
  static properties = ["my-name", "emotion"];
  get template() {
    return `
        <h1>Hello ${this.props.myName}${this.props.emotion === "sad" ? ". 😭" : "! 🙌"}</h1>`;
  }
}

customElements.define('hello-world', HelloWorld);

In your HTML page:

<head>
  <script type="module" src="HelloWorld.mjs"></script>
</head>
<body>
  <hello-world my-name="Ayo" emotion="sad">
  <script>
      const helloWorld = document.querySelector('hello-world');

      setTimeout(() => {
        helloWorld.setAttribute('emotion', 'excited');
      }, 2500)
  </script>
</body>

The result is a reactive UI that updates on attribute changes:

UI showing feeling toward Web Components changing from SAD to EXCITED

`template` vs `render()`

This mental model attempts to reduce the cognitive complexity of authoring components:

The template is a read-only property (initialized with a get keyword) that represents how the component view is rendered.
There is a render() method that triggers a view render.
This render() method is automatically called under the hood every time an attribute value changed.
You can optionally call this render() method at any point to trigger a render if you need (eg, if you have private unobserved properties that need to manually trigger a render)
Overriding the render() function for handling a custom template--where you can return string | Node | (string | Node)[] is also an option. More examples on this to follow.

Prop Access

The props property of the WebComponent interface is provided for easy read/write access to a camelCase counterpart of any observed attribute.

class HelloWorld extends WebComponent {
  static properties = ["my-prop"];
  onInit() {
    let count = 0;
    this.onclick = () => this.props.myProp = `${++count}`
  }
  get template() {
    return `
        <h1>Hello ${this.props.myProp}</h1>
    `;
  }
}

Assigning a value to the props.camelCase counterpart of an observed attribute will trigger an "attribute change" hook.

For example, assigning a value like so:

this.props.myName = 'hello'

...is like calling the following:

this.setAttribute('my-name','hello');

Therefore, this will tell the browser that the UI needs a render if the attribute is one of the component's observed attributes we explicitly provided with static properties = ['my-name'];

Note

The props property of WebComponent works like HTMLElement.dataset, except dataset is only for attributes prefixed with data-. A camelCase counterpart using props will give read/write access to any attribute, with or without the data- prefix. Another advantage over HTMLElement.dataset is that WebComponent.props can hold primitive types 'number', 'boolean', 'object' and 'string'.

Alternatives

The current alternatives are using what HTMLElement provides out-of-the-box, which are:

HTMLElement.dataset for attributes prefixed with data-*. Read more about this on MDN.
Methods for reading/writing attribute values: setAttribute(...) and getAttribute(...); note that managing the attribute names as strings can be difficult as the code grows.

Quick Start Example

Here is an example of using a custom element in a single .html file.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>WC Base Test</title>
    <script type="module">
      import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

      class HelloWorld extends WebComponent {
        static properties = ["my-name"];
        get template() {
          return `<h1>Hello ${this.props.myName}!</h1>`;
        }
      }

      customElements.define("hello-world", HelloWorld);
    </script>
  </head>
  <body>
    <hello-world my-name="Ayo"></hello-world>
    <script>
        const helloWorld = document.querySelector('hello-world');
        setTimeout(() => {
            helloWorld.props.myName = 'Ayo zzzZzzz';
        }, 2500);
    </script>
  </body>
</html>

Life-Cycle Hooks

Define behavior when certain events in the component's life cycle is triggered by providing hook methods

onInit()

Triggered when the component is connected to the DOM
Best for setting up the component

      import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

class ClickableText extends WebComponent {
  // gets called when the component is used in an HTML document
  onInit() {
    this.onclick = () => console.log(">>> click!");
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

afterViewInit()

Triggered after the view is first initialized

class ClickableText extends WebComponent {
  // gets called when the component's innerHTML is first filled
  afterViewInit() {
    const footer = this.querySelector('footer');
    // do stuff to footer after view is initialized
  }

  get template() {
    return `<footer>Awesome site &copy; 2023</footer>`;
  }
}

onDestroy()

Triggered when the component is disconnected from the DOM
best for undoing any setup done in onInit()

      import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

class ClickableText extends WebComponent {
 
  clickCallback() {
    console.log(">>> click!");
  }

  onInit() {
    this.onclick = this.clickCallback;
  }

  onDestroy() {
    console.log(">>> removing event listener");
    this.removeEventListener("click", this.clickCallback);
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

onChanges()

Triggered when an attribute value changed

      import { WebComponent } from "https://unpkg.com/web-component-base@latest/WebComponent.min.js";

class ClickableText extends WebComponent {
  // gets called when an attribute value changes
  onChanges(changes) {
      const {property, previousValue, currentValue} = changes;
      console.log('>>> ', {property, previousValue, currentValue})
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

Library Size

The bundle size was reported to be 587 Bytes (minified & gzipped) by bundlephobia. Running size-limit reports the base class size as around 760 Bytes (minified & brotlied), and using the WebComponent.min.js version gets it down to around 400 Bytes.