Stellar

A stellar way to build reactive custom elements.

Usage

npm install stellar-element@latest

[!WARNING] Stellar is still being actively developed, so all the usual disclaimers apply – here be dragons and such.

What is Stellar?

Stellar is a tiny framework for building a specific flavor of web components called "HTML Web Components."

These web components only use the Custom Elements API and do not use any other APIs you might find in the "web components" bucket, such as Shadow DOM or Templates. Instead, the core premise of HTML web components is to write plain HTML and then simply wrap the parts you want to be interactive using a custom element tag.

For example, while a "regular" web component might look something like this...

<counter-button></counter-button>

...an HTML web component will look like this:

<counter-button>
  <button>Clicked <span>0</span> times</button>
</counter-button>

In the regular web component, component markup is dynamically generated at runtime (using templates and shadow DOM), while the HTML web component simply does the job of hydrating/progressively enhancing existing HTML.

One of the big pain points with HTML web components is that the custom elements API used to build these components is fairly low-level and verbose. Stellar steps in, just like regular web components frameworks (such as Lit or FAST), to improve the ergonomics of building HTML web components.

This is achieved by adding a handful of custom attributes called "directives" that implement event handling and a reactivity model. With Stellar, implementing a counter button looks like this:

<counter-button>
  <button @click="increment">
    Clicked <span $state="count">0</span> times
  </button>
</counter-button>

<script type="module">
  import { Stellar } from 'stellar-element';
  class CounterButton extends Stellar {
    increment = () => this.count++;
  }
  customElements.define('counter-button', CounterButton);
</script>

Learn more by reading our documentation below.

Docs

• Event handling
• Reactivity
• Using Stellar and Astro

Examples

A growing catalog of example code can be found in the examples directory of this repo.

Learn more about HTML web components

These are some great posts that talk about HTML web components in general –– what they are, how they work, and so on.

• HTML web components by Jeremy Keith
• HTML Web Components by Jim Nielsen
• HTML Web Components are Just JavaScript? by Miriam Eric Suzanne
• HTML Web Components by Chris Ferdinandi
• A year working with HTML Web Components by Hawk Ticehurst

Similar projects

Stellar is not the only project helping people build HTML web components. Check them out!

• WebC
• Enhance

License

This project is licensed under MIT. Feel free to use, remix, and adapt the code found in this repo in your own projects.