@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" /> <base href="./building-components.html" /> <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.12.2 </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 id="building-components"> <a name="building-components" class="anchor" href="#building-components"> 🔗 </a> 🏗️ 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 an SPA framework. </section> <section> <h2 id="defining-a-component"> <a name="defining-a-component" class="anchor" href="#defining-a-component"> 🔗 </a> Defining a Component </h2>UIElement builds on Web Components, extending <code>HTMLElement</code> to provide built-in state management and reactive updates. A UIElement creates components using the <code>component()</code> function: <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>component("my-component", {}, () => [ // Component setup ]); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> Every UIElement component must be registered with a valid custom element tag name (two or more words joined with <code>-</code>) as the first parameter. <h3 id="using-the-custom-element-in-html"> <a name="using-the-custom-element-in-html" class="anchor" href="#using-the-custom-element-in-html"> 🔗 </a> 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 id="component-lifecycle"> <a name="component-lifecycle" class="anchor" href="#component-lifecycle"> 🔗 </a> Component Lifecycle </h2>UIElement manages the Web Component lifecycle from creation to removal. Here's what happens. <h3 id="component-creation"> <a name="component-creation" class="anchor" href="#component-creation"> 🔗 </a> Component Creation </h3>In the <code>constructor()</code> reactive properties are initialized. You pass a second argument to the <code>component()</code> function to defines initial values for component states. <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>component("my-component", { count: 0, // Initial value of "count" signal isEven: el => () => !(el.count % 2), // Computed signal based on "count" signal value: asInteger(5), // Parse "value" attribute as integer defaulting to 5 name: consume("display-name") // Consume "display-name" signal from closest context provider }, () => [ // Component setup ]); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> In this example you see all four ways to define a reactive property: <ul> <li>A static initial value for a <code>State</code> signal (e.g., <code>count: 0</code>)</li> <li>A signal producer that derives an initial value or a callback function from other properties of the element (e.g., <code>isEven: el => () => !(el.count % 2)</code>)</li> <li>An attribute parser that may provide a fallback value (e.g., <code>value: asInteger(5)</code>)</li> <li>A context consumer that emits a <code>ContextRequestEvent</code> (e.g., <code>name: consume("display-name")</code>)</li> </ul> <callout-box class="caution"> Note: Property initialization runs before the element is attached to the DOM. You can't access not yet defined properties or child elements here. </callout-box> <h3 id="mounted-in-the-dom"> <a name="mounted-in-the-dom" class="anchor" href="#mounted-in-the-dom"> 🔗 </a> Mounted in the DOM </h3>Runs when the component is added to the page (<code>connectedCallback()</code>). This is where you: <ul> <li>Access sub-elements</li> <li>Set up event listeners</li> <li>Apply effects</li> <li>Emit custom events</li> <li>Provide context</li> </ul> UIElement expects you to return an array of partially applied functions to be executed during the setup phase. The order doesn't matter, as each function targets a specific element or event. So feel free to organize your code in a way that makes sense to you. Each of these functions will return a cleanup function that will be executed during the <code>disconnectedCallback()</code> lifecycle method. <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>component("my-component", { count: 0, }, el => [ emit("update-count", el.count), // Emit custom event provide("count"), // Provide context first(".increment", on("click", () => { el.count++ }) // Add click event listener ), first(".count", setText("count") // Apply effect to update text ) ]); </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 id="removed-from-the-dom"> <a name="removed-from-the-dom" class="anchor" href="#removed-from-the-dom"> 🔗 </a> Removed from the DOM </h3>Runs when the component is removed (<code>disconnectedCallback()</code>). UIElement will run all cleanup functions returned by event listeners and effects during the setup phase (<code>connectedCallback()</code>). This will unsubscribe all signals the component is subscribed to, so you don't need to worry about memory leaks. If you added event listeners outside the scope of your component or subscribed manually to external APIs, you need to return a cleanup function: <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>component("my-component", {}, el => [ // Setup logic () => { const observer = new IntersectionObserver(([entry]) => { // Do something }) observer.observe(el); // Cleanup logic return () => observer.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> <h3 id="observed-attributes"> <a name="observed-attributes" class="anchor" href="#observed-attributes"> 🔗 </a> Observed Attributes </h3>UIElement automatically observes and converts attributes with an associated parser function in the init block and updates them whenever the attribute changes (<code>attributeChangedCallback()</code>). </section> <section> <h2 id="managing-state-with-signals"> <a name="managing-state-with-signals" class="anchor" href="#managing-state-with-signals"> 🔗 </a> Managing State with Signals </h2>UIElement manages state using signals, which are atomic reactive states that trigger updates when they change. We use regular properties to access or update them: <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>console.log("count" in el); // Check if the signal exists console.log(el.count); // Read the signal value el.count = 42; // Update the signal value </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3 id="characteristics-and-special-values"> <a name="characteristics-and-special-values" class="anchor" href="#characteristics-and-special-values"> 🔗 </a> Characteristics and Special Values </h3>Signals in UIElement are of a static 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 id="initializing-state-from-attributes"> <a name="initializing-state-from-attributes" class="anchor" href="#initializing-state-from-attributes"> 🔗 </a> Initializing State from Attributes </h3>The standard way to set initial state in UIElement is via server-rendered attributes on the component that needs it. No props drilling as in other frameworks. UIElements provides some bundled attribute parsers to convert attribute values to the desired type. And you can also define your own custom parsers. <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>component("my-component", { count: asInteger(), // Bundled parser: Convert '42' -> 42 date: (_, v) => new Date(v), // Custom parser: '2025-02-14' -> Date object }, () => [ // Component setup ]); </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 id="bundled-attribute-parsers"> <a name="bundled-attribute-parsers" class="anchor" href="#bundled-attribute-parsers"> 🔗 </a> Bundled Attribute Parsers </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 id="accessing-sub-elements"> <a name="accessing-sub-elements" class="anchor" href="#accessing-sub-elements"> 🔗 </a> Accessing Sub-elements </h2>Before adding event listeners, applying effects, or passing states to sub-elements, you need to select them using a function for element selection: <table> <thead> <tr> <th>Function</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>first(selector, ...fns)</code></td> <td>Selects the first matching element inside the component and applies the given setup functions.</td> </tr> <tr> <td><code>all(selector, ...fns)</code></td> <td>Selects all matching elements inside the component and applies the given setup functions.</td> </tr> </tbody></table> <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>// Select the first ".increment" button and apply effects on it first(".increment", // Fx functions ) // Select all <button> elements and apply effects on them all("button", // Fx functions ) </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> The <code>first()</code> function expects the matched element to be present at connection time. If not, it will silently ignore the call. On the other hand, the <code>all()</code> function creates a dynamic array of elements that will be updated whenever the matching elements are added or removed from the component's DOM branch. UIElement will apply the given setup functions to added elements and run the cleanup functions on removed elements. <callout-box class="tip"> Tip: The <code>all()</code> function is more flexible but also more resource-intensive than <code>first()</code>. Prefer <code>first()</code> when targeting a single element known to be present at connection time. </callout-box> <h3 id="adding-event-listeners"> <a name="adding-event-listeners" class="anchor" href="#adding-event-listeners"> 🔗 </a> Adding Event Listeners </h3>Event listeners allow to respond to user interactions. They are the cause of changes in the component's state. <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>component("my-component", { active: 0, value: '' }, (el) => [ all("button", on("click", (e) => { // Set "active" signal to value of data-index attribute of button const index = parseInt(e.target.dataset['index'], 10); el.active = Number.isInteger(index) ? index : 0; }) ), first("input", on("change", (e) => { // Set "value" signal to value of input element el.value = e.target.value; }) ) ] </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 id="synchronizing-state-with-effects"> <a name="synchronizing-state-with-effects" class="anchor" href="#synchronizing-state-with-effects"> 🔗 </a> Synchronizing State with Effects </h2>Effects automatically update the DOM when signals change, avoiding manual DOM manipulation. <h3 id="applying-effects"> <a name="applying-effects" class="anchor" href="#applying-effects"> 🔗 </a> Applying Effects </h3>Apply one or multiple effects in the setup function (for component itself) or in element selector functions: <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>() => [ // On the component itself setAttribute("open", "isOpen"), // Set "open" attribute according to "isOpen" signal // On first element matching ".count" first(".count", 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> <button type="button" class="overlay">Expand</button> </code-block> Again, the order of effects is not important. Feel free to apply them in any order that suits your needs. <h3 id="bundled-effects"> <a name="bundled-effects" class="anchor" href="#bundled-effects"> 🔗 </a> Bundled Effects </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>dangerouslySetInnerHTML()</code></td> <td>Sets HTML content with a <code>string</code> signal value.</td> </tr> <tr> <td><code>insertOrRemoveElement()</code></td> <td>Inserts (positive integer) or removes (negative integer) elements with a <code>number</code> signal value.</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 pass 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 id="simplifying-effect-notation"> <a name="simplifying-effect-notation" class="anchor" href="#simplifying-effect-notation"> 🔗 </a> 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>first(".count", 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 id="using-local-signals-for-protected-state"> <a name="using-local-signals-for-protected-state" class="anchor" href="#using-local-signals-for-protected-state"> 🔗 </a> Using Local Signals for Protected State </h3>Local signals are useful for storing state that should not be exposed to the outside world. They can be used to manage internal state within a component: <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>component("my-component", {}, () => { const count = state(0); const double = count.map(v => v * 2); return [ first(".increment", on("click", () => { count.update(v => ++v); })), first(".count", setText(count)), first(".double", setText(double)) ]; }); </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> Outside components cannot access the <code>count</code> or <code>double</code> signals. <h3 id="using-functions-for-ad-hoc-derived-state"> <a name="using-functions-for-ad-hoc-derived-state" class="anchor" href="#using-functions-for-ad-hoc-derived-state"> 🔗 </a> Using Functions for Ad-hoc Derived State </h3>Instead of a signal key or a local signal, 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>component("my-component", { count: 0 }, el => { const double = computed(() => el.count * 2); return [ first(".count", toggleClass("even", () => !(el.count % 2)))), first(".double", setText(() => String(double.get()))) ]; }); </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 or a local signal when the state is part of the component's public interface or internally reused.</li> <li>Use a function to derive a value on the fly when it is needed only in this one place.</li> </ul> Ad-hoc derived state is more efficient than the overhead of a memoized computed signal for simple functions like converting to a string or boolean, formatting a value or performing a calculation. </callout-box> <h3 id="efficient-amp-fine-grained-updates"> <a name="efficient-amp-fine-grained-updates" class="anchor" href="#efficient-amp-fine-grained-updates"> 🔗 </a> 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> </section> <section> <h2 id="single-component-example-myslider"> <a name="single-component-example-myslider" class="anchor" href="#single-component-example-myslider"> 🔗 </a> 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" data-index="0"> <h3>Slide 1</h3> <hello-world> <label>Your name <input type="text"> </label> Hello, World! </hello-world> </div> <div class="slide" data-index="1"> <h3>Slide 2</h3> <calc-table rows="3" columns="3"> <div class="rows"> Number of rows: <spin-button value="3" zero-label="Add Row" increment-label="Increment"> <button type="button" class="decrement" aria-label="Decrement"> − </button> 3 <button type="button" class="increment" aria-label="Increment"> + </button> </spin-button> </div> <div class="columns"> Number of columns: <spin-button value="3" zero-label="Add Column" increment-label="Increment" > <button type="button" class="decrement" aria-label="Decrement"> − </button> 3 <button type="button" class="increment" aria-label="Increment"> + </button> </spin-button> </div> <table> <thead> <tr> <th scope="col">Row</th> </tr> <