Getting Started

Web Component Base (WCB) alpha is a zero-dependency, tiny JS base class for creating reactive custom elements easily.

When you extend the WebComponent class for your custom element, you only have to define the template and properties. Any change in an observed property’s value will automatically cause the component UI to render.

The result is a reactive UI on property changes.

Note that there’s a trade off between productivity & lightweight-ness here, and the project aims to help in writing custom elements in the same way more mature and better maintained projects already do. Please look into popular options such as Microsoft’s FASTElement & Google’s LitElement as well.

Project Status

Treat it as a stable alpha product. Though the public APIs are stable, most examples are only useful for simple atomic use-cases due to remaining work needed on the internals.

Important

For building advanced interactions, there is an in-progress work on smart diffing to prevent component children being wiped on interaction.

Tip

If you have some complex needs, we recommend using the WebComponent base class with a more mature rendering approach like lit-html, and here’s a demo for that: View on CodePen.

Installation

The library is distributed as complete ECMAScript Modules (ESM) and published on NPM. Please email a ticket at ~ayoayco/wcb@todo.sr.ht or submit via SourceHut todo for problems or requests regarding our distribution. You can also start a GitHub discussion.

Import via CDN

It is possible to import directly using a CDN like esm.sh or unpkg in your vanilla JS component or HTML files. In all examples in this document, we use unpkg but you can find on CodePen examples that esm.sh also works well.

Additionally, we use @latest in the rest of our usage and examples here for simplicity, but take note that this incurs additional resolution steps for CDNs to find the actual latest published version. You may replace the @latest in the URL with specific versions as shown in our CodePen examples, and this will typically be better for performance.

import { WebComponent } from 'https://unpkg.com/web-component-base@latest/index.js'

Installation via npm

Usable for projects with bundlers or using import maps pointing to the specific files downloaded in node_modules/web-component-base.

npm i web-component-base