@zeix/ui-element

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Building Components – UIElement Docs</title> <meta name="description" content="Anatomy, lifecycle, signals, effects"> <link rel="stylesheet" href="assets/main.css"> <script type="module" src="assets/main.js"></script> </head> <body> <header class="content-grid"> <h1 class="content">UIElement Docs Version 0.11.0</h1> <nav class="breakout"> <ol> <li> <a href="index.html"> 📖 Introduction Overview and key benefits of UIElement </a> </li> <li> <a href="getting-started.html"> 🚀 Getting Started Installation, setup, and first steps </a> </li> <li> <a href="building-components.html" class="active"> 🏗️ Building Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling-components.html"> 🎨 Styling Components Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="patterns-techniques.html"> 💡 Patterns & Techniques Composition, scheduling, best practices </a> </li> <li> <a href="examples-recipes.html"> 🍽️ Examples & Recipes Common use cases and demos </a> </li> <li> <a href="api-reference.html"> 📚 API Reference Detailed documentation of classes and functions </a> </li> <li> <a href="about-community.html"> 🤝 About & Community License, versioning, getting involved </a> </li> </ol> </nav> </header> <main> <section class="hero"> <h1>🏗️ Building Components</h1> Create lightweight, self-contained Web Components with built-in reactivity. UIElement lets you define custom elements that manage state efficiently, update the DOM automatically, and enhance server-rendered pages without a framework. </section> <section> <h2>Anatomy of a UIElement Component</h2> UIElement builds on Web Components, extending <code>HTMLElement</code> to provide built-in state management and reactive updates. <h3>Defining a Component</h3> A UIElement component is created by extending <code>UIElement</code>: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class MyComponent extends UIElement { /* component definition */ } </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Registering a Custom Element</h3> Every UIElement component must be registered with a valid custom tag name (two or more words joined with <code>-</code>) using <code>.define()</code>. <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>MyComponent.define('my-component'); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <callout-box class="tip"> Alternative: If you prefer you can also declare the custom element tag within the component and call <code>.define()</code> without arguments. <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class MyComponent extends UIElement { static localName = 'my-component'; /* component definition */ } MyComponent.define() </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </callout-box> <h3>Using the Custom Element in HTML</h3> Once registered, the component can be used like any native HTML element: <code-block language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><my-component>Content goes here</my-component> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </section> <section> <h2>Web Component Lifecycle in UIElement</h2> Every UIElement component follows a lifecycle from creation to removal. Here's how the key lifecycle methods work: <h3>Component Creation (constructor())</h3> Runs when the element is created but before it's attached to the DOM. Avoid accessing attributes or child elements here. <h3>Mounted in the DOM (connectedCallback())</h3> Runs when the component is added to the page. This is where you: <ul> <li>✅ Initialize state</li> <li>✅ Set up event listeners</li> <li>✅ Apply effects</li> </ul> <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class MyComponent extends UIElement { connectedCallback() { this.first('.increment').on('click', () => { // Add click event listener this.set('count', v => null != v ? ++v : 1); }); this.first('.count').sync(setText('count')); // Apply effect to update text } } </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> If your component initializes states from <code>states</code> or provides or consumes context (<code>static providedContexts</code> / <code>static consumedContexts</code>), you need to call <code>super.connectedCallback()</code>. <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class HelloUser extends UIElement { static consumedContexts = ['display-name']; // Signal provided by a parent component init = { greeting: 'Hello', // Initial value of 'greeting' signal upper: () => this.get('display-name').toUpperCase(), // Compute function for transformation on 'display-name' signal } connectedCallback() { super.connectedCallback(); // Initializes state signals from values, attributes, context or creates computed signals from functions this.first('.greeting').sync(setText('greeting')); this.first('.user').sync(setText('display-name')); this.first('.profile h2').sync(setText('upper')); } } </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> <h3>Removed from the DOM (disconnectedCallback())</h3> Runs when the component is removed. Event listeners bound with <code>.on()</code> are automatically removed by UIElement. If you added event listeners outside the scope of your component or external subscriptions, you need to manually clean up. <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class MyComponent extends UIElement { connectedCallback() { this.intersectionObserver = new IntersectionObserver(([entry]) => { // Do something }).observe(this); } disconnentedCallback() { super.disconnectedCallback(); // Automatically removes event listeners bound with `.on()` if (this.intersectionObserver) this.intersectionObserver.disconnect(); } } </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> Use this to clean up event listeners or external subscriptions. <h3>Observed Attributes (attributeChangedCallback())</h3> UIElement automatically converts attributes to reactive signals. Usually, you don’t need to override this method manually. </section> <section> <h2>State Management with UIElement</h2> UIElement manages state using signals, which are reactive values that trigger updates when they change. We use a familiar <code>Map</code>-like API: <h3>Defining & Using Signals</h3> <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.set('count', 0); // Create a state signal this.set('isEven', () => !((this.get('count') ?? 0) % 2)); // Create a derived signal </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Checking & Removing Signals</h3> <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>if (this.has('count')) { /* Do something */ } this.delete('count'); // Removes the signal and its dependencies </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Characteristics and Special Values</h3> Signals in UIElement are of a fixed type and non-nullable. This allows to simplify the logic as you will never have to check the type or perform null-checks. <ul> <li>If you use TypeScript (recommended), you will be warned that <code>null</code> or <code>undefined</code> cannot be assigned to a signal or if you try to assign a value of a wrong type.</li> <li>If you use vanilla JavaScript without a build step, setting a signal to <code>null</code> or <code>undefined</code> will log an error to the console and abort. However, strict type checking is not enforced at runtime.</li> </ul> Because of the non-nullable nature of signals in UIElement, we need two special values that can be assigned to any signal type: <ul> <li><code>RESET</code>: Will reset to the server-rendered version that was there before UIElement took control. This is what you want to do most of the times when a signal lacks a specific value.</li> <li><code>UNSET</code>: Will delete the signal, unsubscribe its watchers and also delete related attributes or style properties in effects. Use this with special care!</li> </ul> <h3>Why Signals with a Map Interface?</h3> UIElement uses signals instead of standard properties or attributes because it ensures reactivity, loose coupling, and avoids common pitfalls with the DOM API. <ul> <li>✅ Signals enable loose coupling between components: A component that modifies state doesn’t need to know which or how many elements depend on that state. Any UI updates happen automatically wherever that signal is used.</li> <li>✅ Signals trigger automatic updates: Any DOM element or effect that depends on a signal updates itself when the signal changes. The source doesn't need to know how the updated state should change the DOM.</li> <li>✅ Standard JavaScript properties are not reactive: JavaScript properties don’t automatically trigger updates when changed. The distinct <code>Map</code>-like interface avoids confusion.</li> <li>✅ Attributes can only store strings: Attributes in HTML are always strings. If you store numbers, booleans, or objects, you must manually convert them between string format and usable values. Signals avoid this extra conversion step.</li> <li>✅ The Map interface avoids name conflicts:<ul> <li>The <code>HTMLElement</code> namespace is crowded, meaning using direct properties can accidentally override existing methods or properties.</li> <li>HTML attributes are kebab-case (<code>data-user-id</code>), but JavaScript properties are camelCase (<code>dataUserId</code>), which can cause inconsistencies.</li> <li>With a Map, we can use attributes names directly as state keys (e.g., <code>"count"</code> or <code>"is-active"</code>) without conversion or worrying about naming conflicts.</li> </ul> </li> </ul> </section> <section> <h2>Initializing State from Attributes</h2> <h3>Declaring Observed Attributes</h3> <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>static observedAttributes = ['count']; // Automatically becomes a signal </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Parsing Attribute Values</h3> <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>init = { count: asInteger(), // Convert '42' -> 42 date: v => new Date(v), // Custom parser: '2025-02-14' -> Date object }; </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <callout-box class="caution"> Careful: Attributes may not be present on the element or parsing to the desired type may fail. To ensure non-nullability of signals, UIElement falls back to neutral defaults: <ul> <li><code>''</code> (empty string) for <code>string</code></li> <li><code>0</code> for <code>number</code></li> <li><code>{}</code> (empty object) for objects of any kind</li> </ul> </callout-box> <h3>Pre-defined Parsers in UIElement</h3> <table> <thead> <tr> <th>Function</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>asBoolean</code></td> <td>Converts <code>"true"</code> / <code>"false"</code> to a boolean (<code>true</code> / <code>false</code>). Also treats empty attributes (<code>checked</code>) as <code>true</code>.</td> </tr> <tr> <td><code>asInteger()</code></td> <td>Converts a numeric string (e.g., <code>"42"</code>) to an integer (<code>42</code>).</td> </tr> <tr> <td><code>asNumber()</code></td> <td>Converts a numeric string (e.g., <code>"3.14"</code>) to a floating-point number (<code>3.14</code>).</td> </tr> <tr> <td><code>asString()</code></td> <td>Returns the attribute value as a string (unchanged).</td> </tr> <tr> <td><code>asEnum([...])</code></td> <td>Ensures the string matches one of the allowed values. Example: <code>asEnum(['small', 'medium', 'large'])</code>. If the value is not in the list, it defaults to the first option.</td> </tr> <tr> <td><code>asJSON({...})</code></td> <td>Parses a JSON string (e.g., <code>'["a", "b", "c"]'</code>) into an array or object. If invalid, returns the fallback object.</td> </tr> </tbody></table> The pre-defined parsers <code>asInteger()</code>, <code>asNumber()</code> and <code>asString()</code> allow to set a custom fallback value as parameter. The <code>asEnum()</code> parser requires an array of valid values, while the first will be the fallback value for invalid results. The <code>asJSON()</code> parser requires a fallback object as parameter as <code>{}</code> probably won't match the type you're expecting. </section> <section> <h2>Accessing Sub-elements within the Component</h2> Before adding event listeners, applying effects, or passing states, you need to select elements inside the component. UIElement provides the following methods for element selection: <table> <thead> <tr> <th>Method</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>this.self</code></td> <td>Selects the component itself.</td> </tr> <tr> <td><code>this.first(selector)</code></td> <td>Selects the first matching element inside the component.</td> </tr> <tr> <td><code>this.all(selector)</code></td> <td>Selects all matching elements inside the component.</td> </tr> </tbody></table> <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>// Select the component itself this.self.sync(setProperty('hidden')); // Select the first '.increment' button & add a click event this.first('.increment').on('click', () => { this.set('count', v => null != v ? ++v : 1); }); // Select all <button> elements & sync their 'disabled' properties this.all('button').sync(setProperty('disabled', 'hidden')); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> </section> <section> <h2>Updating State with Events</h2> User interactions should update signals, not the DOM directly. This keeps the components loosly coupled. Bind event handlers to one or many elements using the <code>.on()</code> method: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.first('.increment').on('click', () => { this.set('count', v => null != v ? v++ : 1) }); this.first('input').on('input', e => { this.set('name', e.target.value || undefined) }); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </section> <section> <h2>Synchronizing State with Effects</h2> Effects automatically update the DOM when signals change, avoiding manual DOM manipulation. <h3>Applying Effects with .sync()</h3> Apply one or multiple effects to elements using <code>.sync()</code>: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.first('.count').sync( setText('count'), // Update text content according to 'count' signal toggleClass('even', 'isEven') // Toggle 'even' class according to 'isEven' signal ); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Pre-defined Effects in UIElement</h3> <table> <thead> <tr> <th>Function</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>setText()</code></td> <td>Updates text content with a <code>string</code> signal value (while preserving comment nodes).</td> </tr> <tr> <td><code>setProperty()</code></td> <td>Updates a given property with any signal value.*</td> </tr> <tr> <td><code>setAttribute()</code></td> <td>Updates a given attribute with a <code>string</code> signal value.</td> </tr> <tr> <td><code>toggleAttribute()</code></td> <td>Toggles a given boolean attribute with a <code>boolean</code> signal value.</td> </tr> <tr> <td><code>toggleClass()</code></td> <td>Toggles a given CSS class with a <code>boolean</code> signal value.</td> </tr> <tr> <td><code>setStyle()</code></td> <td>Updates a given CSS property with a <code>string</code> signal value.</td> </tr> <tr> <td><code>createElement()</code></td> <td>Inserts a new element with a given tag name with a <code>Record<string, string></code> signal value for attributes.</td> </tr> <tr> <td><code>removeElement()</code></td> <td>Removes an element if the <code>boolean</code> signal value is <code>true</code>.</td> </tr> </tbody></table> <callout-box class="tip"> Tip: TypeScript will check whether a value of a given type is assignable to a certain element type. You might have to specify a type hint for the queried element type. Prefer <code>setProperty()</code> over <code>setAttribute()</code> for increased type safety. Setting string attributes is possible for all elements, but will have an effect only on some. </callout-box> <h3>Simplifying Effect Notation</h3> For effects that take two arguments, the second argument can be omitted if the signal key matches the targeted property name, attribute, class, or style property. When signal key matches property name: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.first('.count').sync(toggleClass('even')); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> Here, <code>toggleClass('even')</code> automatically uses the <code>"even"</code> signal. <h3>Using Functions for Ad-hoc Derived State</h3> Instead of a signal key, you can pass a function that derives a value dynamically: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.first('.count').sync(toggleClass('even', () => !((this.get('count') ?? 0) % 2))); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <callout-box class="tip"> When to use <ul> <li>Use a signal key when the state is already stored as a signal.</li> <li>Use a function when you derive a value on the fly needed only in this one place and you don't want to expose it as a signal on the element.</li> </ul> </callout-box> <h3>Custom Effects</h3> For complex DOM manipulations, define your own effect using <code>effect()</code>. Here's an example effect that attaches a Shadow DOM and updates its content: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>// Update the shadow DOM when content changes effect(() => { const content = this.get('content') if (content) { this.root = this.shadowRoot || this.attachShadow({ mode: 'open' }) this.root.innerHTML = content } }); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Efficient & Fine-Grained Updates</h3> Unlike some frameworks that re-render entire components, UIElement updates only what changes: <ul> <li>✅ No virtual DOM – UIElement modifies the DOM directly.</li> <li>✅ Signals propagate automatically – No need to track dependencies manually.</li> <li>✅ Optimized with a scheduler – Multiple updates are batched efficiently.</li> </ul> In practical terms: UIElement is as easy as React but without re-renders. </section> <section> <h2>Single Component Example: MySlider</h2> Bringing all of the above together, you are now ready to build your own components like this slider with prev / next buttons and dot indicators, demonstrating single-component reactivity. <component-demo> <div class="preview"> <my-slider> <h2 class="visually-hidden">Slides</h2> <div class="slides"> <div class="slide active"> <h3>Slide 1</h3> <hello-world> <label>Your name <input type="text"> </label> Hello, World! </hello-world> </div> <div class="slide"> <h3>Slide 2</h3> <spin-button value="0" zero-label="Add to Cart" increment-label="Increment"> <button type="button" class="decrement" aria-label="Decrement" hidden>−</button> 0 <button type="button" class="increment primary">Add to Cart</button> </spin-button> </div> <div class="slide"> <h3>Slide 3</h3> <rating-feedback> <form> <rating-stars> <fieldset> <legend class="visually-hidden">Rate</legend> <label> <input type="radio" class="visually-hidden" name="rating" value="1"> ☆ </label> <label> <input type="radio" class="visually-hidden" name="rating" value="2"> ☆ </label> <label> <input type="radio" class="visually-hidden" name="rating" value="3"> ☆ </label> <label> <input type="radio" class="visually-hidden" name="rating" value="4"> ☆ </label> <label> <input type="radio" class="visually-hidden" name="rating" value="5"> ☆ </label> </fieldset> </rating-stars> <div class="feedback" hidden> <header> <button button="button" class="hide" aria-label="Hide">×</button> We're sorry to hear that! Your feedback is important, and we'd love to improve. Let us know how we can do better. Thank you for your honesty. We appreciate your feedback and will work on making things better. Thanks for your rating! If there's anything we can improve, we'd love to hear your thoughts. We're glad you had a good experience! If there's anything that could make it even better, let us know. Thank you for your support! We're thrilled you had a great experience. Your feedback keeps us motivated! </header> <fieldset> <label for="rating-feedback">Describe your experience (optional)</label> <textarea id="rating-feedback"></textarea> <input-button disabled> <button type="submit" class="primary" disabled>Submit</button> </input-button> </fieldset> </div> </form> </rating-feedback> </div> </div> <button type="button" class="prev" aria-label="Previous">‹<