Web Component Base

Note

Correctness fixes shipped (v5.0.0) — We now have better compliance with the custom elements specs, better property type handling and clearer distinction between attributes and property within onChanges() hook (breaking change). See the change log for more details. Next up: faster templates!

🤷‍♂️ zero-dependency, 🤏 tiny JS base class for creating reactive custom elements easily ✨

This is the base class used for web components in Ayo's projects, primarily cozy-games, mcfly, his personal site, his blog, and others.

Read more about it on the docs or view a demo on CodePen.

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.

TypeScript: typed props

this.props is untyped ({ [name: string]: any }) by default. Pass the shape of your defaults as a type argument to get compile-time types on declared props:

const props = { variant: 'primary', disabled: false }

class CozyButton extends WebComponent<typeof props> {
  static props = props

  get template() {
    this.props.variant // string
    this.props.disabled // boolean
    this.props.disabled = 'yes' // ❌ compile error
    return html`<button class=${this.props.variant}></button>`
  }
}

The runtime is unchanged — this is types-only, and omitting the type argument keeps the previous behavior. See the prop access guide for details.

Storybook autodocs & controls

Storybook infers autodocs and controls from a Custom Elements Manifest, but the stock analyzer reads static props as one opaque object and emits no attributes. web-component-base/cem-plugin teaches it the convention — dev-time only, so the core stays zero-dependency:

// custom-elements-manifest.config.mjs
import { wcbStaticProps } from 'web-component-base/cem-plugin'

export default {
  globs: ['src/**/*.js'],
  outdir: '.',
  plugins: [wcbStaticProps()],
}

npx cem analyze then emits a typed attribute per prop — variant (string), disabled (boolean), maxCount → max-count (number) — named with wcb's own getKebabCase so they match observedAttributes, with wcb internals stripped. Point Storybook at the result:

// .storybook/preview.js
import { setCustomElementsManifest } from '@storybook/web-components-vite'
import manifest from '../custom-elements.json'

setCustomElementsManifest(manifest)
export default { tags: ['autodocs'] }

A story only needs component: 'cozy-button' — no per-story argTypes. See the full recipe, or the working setup in storybook/.

Want to get in touch?

There are many ways to get in touch:

1. Open a GitHub issue or discussion
2. Submit a ticket via SourceHut todo
3. Email me: hi@ayo.run

Inspirations and thanks

1. htm - I use it for the html function for tagged templates, and take a lot of inspiration in building the rendering implementation. It is highly likely that I will go for what Preact is doing... but we'll see.
2. fast - When I found that Microsoft has their own base class I thought it was super cool!
3. lit - lit-html continues to amaze me and I worked to make wcb generic so I (and others) can continue to use it

Size change log

See size-change-log.md for a running record of how each correctness/feature change affects the WebComponent base class bundle size, with the reason and benefit of each.

---

Just keep building.
A project by Ayo