---
title: Getting Started
slug: getting-started
---

import { Aside, Badge } from '@astrojs/starlight/components';

**Web Component Base (WCB)** 
<Badge text="alpha" variant="danger" /> is a zero-dependency, tiny JS base class for creating reactive [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components/Using_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](https://fast.design/) & [Google's LitElement](https://lit.dev/) 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.

<Aside type="caution" title="Important">
For building advanced interactions, there is an in-progress work on smart diffing to prevent component children being wiped on interaction.
</Aside>

<Aside type="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](https://codepen.io/ayoayco-the-styleful/pen/ZEwNJBR?editors=1010).
</Aside>

## Installation

The library is distributed as complete ECMAScript Modules (ESM) and published on [NPM](https://ayco.io/n/web-component-base). Please 
email a ticket at [~ayoayco/wcb@todo.sr.ht](mailto:~ayoayco/wcb@todo.sr.ht) or submit via [SourceHut todo](https://todo.sr.ht/~ayoayco/wcb)
for problems or requests regarding our distribution. You can also start a [GitHub discussion](https://github.com/ayoayco/wcb/discussions).

### Import via CDN

It is possible to import directly using a CDN like [esm.sh](https://esm.sh/web-component-base) or [unpkg](https://unpkg.com/web-component-base) 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](/usage) and [examples](/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.

```js
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`.

```bash
npm i web-component-base
```