@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>Components – UIElement Docs</title> <meta name="description" content="Anatomy, lifecycle, signals, effects" /> <link rel="preload" href="./assets/main.css?v=452f3291" as="style" /> <link rel="modulepreload" href="./assets/main.js?v=4387827c" /> <link rel="stylesheet" href="./assets/main.css?v=452f3291" /> <script type="module" src="./assets/main.js?v=4387827c" ></script> </head> <body class=""> <context-router> <header class="content-grid"> <a href="#main" class="skiplink visually-hidden"> Skip to main content </a> <h1 class="content"> UIElement Docs Version 0.14.0 </h1> <section-menu> <nav> <h2 class="visually-hidden">Main Menu</h2> <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="components.html"> 🏗️ Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling.html"> 🎨 Styling Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="examples.html"> 🍽️ Examples Common use cases and demos </a> </li> <li> <a href="blog.html"> 📜 Blog Latest articles and updates </a> </li> <li> <a href="api.html"> 📚 API Reference Functions, types, and constants </a> </li> <li> <a href="about.html"> 🤝 About License, versioning, getting involved </a> </li> </ol> </nav> </section-menu> <card-callout class="content danger" hidden> </card-callout> </header> <main id="main" class="content-grid"><section-hero> <h1 id="components"> <a name="components" class="anchor" href="#components"> 🔗 🏗️ Components </a> </h1> <div> 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. <module-toc> <nav> <h2>In This Page</h2> <ol> <li><a href="#defining-a-component">Defining a Component</a></li> <li><a href="#component-lifecycle">Component Lifecycle</a></li> <li><a href="#managing-state-with-signals">Managing State with Signals</a></li> <li><a href="#selecting-elements">Selecting Elements</a></li> <li><a href="#adding-event-listeners">Adding Event Listeners</a></li> <li><a href="#synchronizing-state-with-effects">Synchronizing State with Effects</a></li> <li><a href="#next-steps">Next Steps</a></li> </ol> </nav> </module-toc> </div> </section-hero> <section> <h2 id="defining-a-component"> <a name="defining-a-component" class="anchor" href="#defining-a-component"> 🔗 Defining a Component </a> </h2> UIElement builds on Web Components, extending <code>HTMLElement</code> to provide built-in state management and reactive updates. UIElement creates components using the <code>component()</code> function: <module-codeblock 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> 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"> 🔗 Using the Custom Element in HTML </a> </h3> Once registered, the component can be used like any native HTML element: <module-codeblock 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h3 id="anatomy-of-a-component"> <a name="anatomy-of-a-component" class="anchor" href="#anatomy-of-a-component"> 🔗 Anatomy of a Component </a> </h3> Let's examine a complete component example to understand how UIElement works: <module-codeblock 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( 'hello-world', { name: asString(el => el.querySelector('span')?.textContent?.trim() ?? ''), }, (el, { first }) => { const fallback = el.name return [ first( 'input', on('input', ({ target }) => ({ name: target.value || fallback })), ), first('span', setText('name')), ] }, ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <h4 id="reactive-properties"> <a name="reactive-properties" class="anchor" href="#reactive-properties"> 🔗 Reactive Properties </a> </h4> <module-codeblock 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>{ // Create "name" property from attribute "name" as a string, falling back to server-rendered content name: asString(el => el.querySelector('span')?.textContent?.trim() ?? ''), } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> This creates a reactive property called <code>name</code>: <ul> <li><code>asString()</code> observes the attribute <code>name</code> and assigns its value as a string to the <code>name</code> property</li> <li><code>el => ...</code> is an instruction how to get the fallback value in the DOM if there is no name attribute</li> <li>UIElement automatically reads "World" from the <code></code> element as the initial value</li> <li>When <code>name</code> changes, any effects that depend on it automatically update</li> </ul> <h4 id="setup-function"> <a name="setup-function" class="anchor" href="#setup-function"> 🔗 Setup Function </a> </h4> The setup function takes two arguments: <ol> <li>The component element. In this example we name it <code>el</code>.</li> <li>Helper functions for accessing descendant elements. In this example we use <code>first</code> to find the first descendant matching a selector and apply effects to it.</li> </ol> The setup function returns an array of effects: <module-codeblock 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>(el, { first }) => { // set the fallback value we want to use instead of an empty string const fallback = el.name return [ // Handle user input to change the "name" property first( 'input', on('input', ({ target }) => ({ name: target.value || fallback })), ), // Update content when the "name" property changes first('span', setText('name')), ] }, </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> Effects define component behaviors: <ul> <li><code>first('input', on('input', ...))</code> finds the first <code><input></code> and adds an event listener</li> <li><code>first('span', setText('name'))</code> finds the first <code></code> and keeps its text in sync with the <code>name</code> property</li> </ul> Characteristics of Effects: <ul> <li>Effects run when the component is added to the page</li> <li>Effects rerun when their dependencies change</li> <li>Effects may return a cleanup function to be executed when the target element or the component is removed from the page</li> </ul> </section> <section> <h2 id="component-lifecycle"> <a name="component-lifecycle" class="anchor" href="#component-lifecycle"> 🔗 Component Lifecycle </a> </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"> 🔗 Component Creation </a> </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. <module-codeblock 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, // Initial value of "count" signal value: asInteger(5), // Parse "value" attribute as integer defaulting to 5 isEven: el => () => !(el.count % 2), // Computed signal based on "count" signal name: fromContext('display-name', 'World'), // Consume "display-name" signal from closest context provider }, () => [ // Component setup ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> In this example you see all three 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>An attribute parser that may provide a fallback value (e.g., <code>value: asInteger(5)</code>)</li> <li>A signal producer function that derives an initial value or a callback function from other properties of the element (e.g., <code>isEven: el => () => !(el.count % 2)</code>) or bundled signal producers (e.g. <code>fromContext(context, fallback)</code>)</li> </ul> <card-callout class="caution"> Caution: Property initialization runs before the element is attached to the DOM. You can't access not yet defined properties or descendant elements here. </card-callout> <h3 id="mounted-in-the-dom"> <a name="mounted-in-the-dom" class="anchor" href="#mounted-in-the-dom"> 🔗 Mounted in the DOM </a> </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> The setup function has two arguments: <ol> <li><code>el</code>: The component element instance.</li> <li><code>{ all, first }</code>: An object containing two functions, <code>all</code> and <code>first</code>, which can be used to select elements within the component. See <a href="#accessing-sub-elements">Accessing Sub-elements</a>.</li> </ol> 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. <module-codeblock 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, { first }) => [ 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <h3 id="removed-from-the-dom"> <a name="removed-from-the-dom" class="anchor" href="#removed-from-the-dom"> 🔗 Removed from the DOM </a> </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: <module-codeblock 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <h3 id="observed-attributes"> <a name="observed-attributes" class="anchor" href="#observed-attributes"> 🔗 Observed Attributes </a> </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"> 🔗 Managing State with Signals </a> </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: <module-codeblock 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h3 id="characteristics-and-special-values"> <a name="characteristics-and-special-values" class="anchor" href="#characteristics-and-special-values"> 🔗 Characteristics and Special Values </a> </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"> 🔗 Initializing State from Attributes </a> </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. <module-codeblock 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: asInteger(), // Bundled parser: Convert '42' -> 42 date: (_, v) => new Date(v), // Custom parser: '2025-02-14' -> Date object }, () => [ // Component setup ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <card-callout 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> </card-callout> <h3 id="bundled-attribute-parsers"> <a name="bundled-attribute-parsers" class="anchor" href="#bundled-attribute-parsers"> 🔗 Bundled Attribute Parsers </a> </h3> UIElement provides several built-in parsers for common attribute types. See the <a href="api.html#parsers">Parsers section</a> in the API reference for detailed descriptions and usage examples. </section> <section> <h2 id="selecting-elements"> <a name="selecting-elements" class="anchor" href="#selecting-elements"> 🔗 Selecting Elements </a> </h2> Use the provided selector utilities to find elements within your component: <h3 id="first"> <a name="first" class="anchor" href="#first"> 🔗 first() </a> </h3> Selects the first matching element and applies effects: <module-codeblock 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( 'basic-counter', { count: asInteger(), }, (el, { first }) => [ first('.count', setText('count')), first( 'button', on('click', () => { el.count++ }), ), ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <h3 id="all"> <a name="all" class="anchor" href="#all"> 🔗 all() </a> </h3> Selects all matching elements and applies effects to each: <module-codeblock 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( 'module-tabgroup', { selected: '', }, (el, { all }) => [ // Apply click handler to all buttons all( '[role="tab"]', on('click', e => { el.selected = e.currentTarget?.getAttribute('aria-controls') ?? '' }), setProperty( 'ariaSelected', target => target?.getAttribute('aria-controls') === el.selected, ), setProperty('tabIndex', target => target?.getAttribute('aria-controls') === el.selected ? 0 : -1, ), ), // Apply hidden property to all tabs all( '[role="tabpanel"]', show(target => el.selected === target.id), ), ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> 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. <card-callout 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. </card-callout> </section> <section> <h2 id="adding-event-listeners"> <a name="adding-event-listeners" class="anchor" href="#adding-event-listeners"> 🔗 Adding Event Listeners </a> </h2> Event listeners allow to respond to user interactions. They are the cause of changes in the component's state. <module-codeblock 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, first }) => [ 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 =><span style="color:#F