@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>The Case for Components – UIElement Docs</title> <meta name="description" content="Components are a proven way to reduce complexity, encourage reuse, and allow teams to scale their work across independent user interface parts." /> <link rel="stylesheet" href="../assets/main.css" /> <script type="module" src="../assets/main.js"></script> </head> <body class="blog"> <context-router> <header class="content-grid"> <h1 class="content"> UIElement Docs Version 0.13.3 </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 class="content-grid"><section-hero> <h1 id="the-case-for-components"> <a name="the-case-for-components" class="anchor" href="#the-case-for-components"> 🔗 </a> The Case for Components </h1> <div> Components are a proven way to reduce complexity, encourage reuse, and allow teams to scale their work across independent user interface parts. But you don't need a framework to get these benefits. Let's explore how components help us build better interfaces – and how native Web Components and UIElement fit into that picture. <module-toc> <nav> <h2>In this Page</h2> <ol> <li><a href="#why-components">Why Components?</a></li> <li><a href="#you-dont-need-a-framework-for-that">You Don't Need a Framework for That</a></li> <li><a href="#a-solid-foundation">A Solid Foundation</a></li> <li><a href="#takeaways">Takeaways</a></li> <li><a href="#coming-up-next-rethinking-reactivity">Coming Up Next: Rethinking Reactivity</a></li> </ol> </nav> </module-toc> </div> </section-hero> <section> <h2 id="why-components"> <a name="why-components" class="anchor" href="#why-components"> 🔗 </a> Why Components? </h2> The idea of organizing user interfaces into components became mainstream with React over a decade ago, when Pete Hunt explained its core benefit: reduce coupling, increase cohesion. Instead of writing large, monolithic pages where styling, behavior, and data flow are all tangled together, components encourage you to break your user interface into small, focused pieces that each: <ul> <li>Own their internal structure and styles,</li> <li>Expose a clear public interface (via attributes or properties),</li> <li>And optionally encapsulate logic for interaction, validation, or data binding.</li> </ul> This separation of concerns helps in multiple ways: <ul> <li>Local reasoning: You can understand and test a component in isolation.</li> <li>Reusability: A component written once can be used anywhere.</li> <li>Parallel development: Teams can divide work by component boundaries.</li> </ul> As requirements grow – new features, edge cases, accessibility tweaks – components give you a way to evolve your user interface incrementally. You don't have to rewrite your app. You just enhance or replace parts of it. These benefits sound framework-specific, but they're not. The Web Platform itself provides everything you need to build components – let's see how. </section> <section> <h2 id="you-dont-need-a-framework-for-that"> <a name="you-dont-need-a-framework-for-that" class="anchor" href="#you-dont-need-a-framework-for-that"> 🔗 </a> You Don't Need a Framework for That </h2> Frameworks like React, Vue, or Svelte give you component models out of the box – but they aren't the only way. In fact, the Web Platform itself has a native component model: Web Components. Web Components allow you to define your own HTML tags with scoped or encapsulated behavior and styles. Let's look at a simple example: <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><hello-world>Hello, world!</hello-world> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> Underwhelmed because it's just HTML? – Well, that's the whole point! For now, it's just a custom element. But it gives you already a way to unambiguously scope your styles to your components. <module-codeblock language="css" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> css <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>hello-world { display: block; padding: 1rem; border: 1px solid #ccc; border-radius: 0.25rem; } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> Let's add some interactivity: <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><hello-world> <label> Your name <input type="text" /> </label> <p>Hello, <span>world</span>!</p> </hello-world> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> Add the following to your JavaScript for the page: <module-codeblock language="javascript" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> javascript <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>class HelloWorld extends HTMLElement { connectedCallback() { const nameEl = this.querySelector('span') this.querySelector('input')?.addEventListener('input', e => { if (nameEl) nameEl.textContent = e.target.value }) } } customElements.define('hello-world', HelloWorld) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> Web Components are registered using <code>customElements.define()</code> and automatically upgrade when they appear in the DOM – no bundler magic or runtime library required. Now, our <code>hello-world</code> component reacts to user input and updates the greeting accordingly. No external dependencies, just plain JavaScript and the browser's built-in APIs and it works – everywhere! </section> <section> <h2 id="a-solid-foundation"> <a name="a-solid-foundation" class="anchor" href="#a-solid-foundation"> 🔗 </a> A Solid Foundation </h2> UIElement builds on the Web Platform rather than abstracting over it. We embrace semantic HTML as the foundation. Add CSS to your components however you like and make them look great. Use Web Components to add reusable behavior. While native Web Components are powerful, they require you to wire things together manually – querying elements, adding event listeners, and managing updates. This works great for simple interactions, but what if we want other components or JavaScript code to control our component's state? Let's add a public API. To achieve this, we can expose an observed attribute and a public property. Observed attributes allow our component to react when the attribute changes. Element properties usually mirror attributes, but they can be of any type, not just strings. We need a setter function to react to changes in the property. <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>class HelloWorld extends HTMLElement { static observedAttributes = ['name'] #name = '' connectedCallback() { this.querySelector('input')?.addEventListener('input', e => { this.name = e.target.value }) } attributeChangedCallback(name, oldValue, newValue) { if (name === 'name') { this.name = newValue } } get name() { return this.#name } set name(value) { this.#name = value const nameEl = this.querySelector('span') if (nameEl) nameEl.textContent = this.name } } customElements.define('hello-world', HelloWorld) </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> Hooray, now we can set the name from outside the component in HTML: <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><hello-world name="Ada"></hello-world> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> ... or via JavaScript: <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>const helloWorld = document.querySelector('hello-world') helloWorld.name = 'Betty' </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> This manual wiring works, but notice how much boilerplate we needed for a simple reactive property. As components grow more complex, this pattern becomes harder to maintain. This is where UIElement shines – it provides the reactivity patterns you need while staying close to the platform. Here's the same component rewritten using UIElement. Notice how the concerns are cleanly separated: <ul> <li>State declaration: <code>name: asString()</code> defines our component's reactive state</li> <li>Input handling: The <code>on('input', ...)</code> handler updates state declaratively</li> <li>DOM updates: <code>setText('name')</code> automatically keeps the display in sync</li> </ul> <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>import { component, asString, on, setText } from '@zeix/ui-element' component( 'hello-world', { name: asString(), }, (el, { first }) => [ first( 'input', on('input', e => { el.name = e.target.value }), ), 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> This scales much better as complexity grows. You could add default values, validation rules, attribute reflection, or derived values – all while keeping effects and state management declarative and contained. The functions we use: <ul> <li><code>component()</code> creates a Web Component with less boilerplate.</li> <li><code>asString()</code> does nothing, but tells TypeScript that state <code>name</code> is a for sure a string.</li> <li><code>first()</code> selects the first element matching a selector.</li> <li><code>on()</code> adds an event listener to an element and removes it when the component is disconnected.</li> <li><code>setText()</code> updates the text content of an element when a state change occurs.</li> </ul> Components in UIElement are still standard Web Components that can be used everywhere. Other components need to know nothing more about UIElement components other than they are standard HTML elements with a few reactive properties according to a clearly defined contract – its public interface. </section> <section> <h2 id="takeaways"> <a name="takeaways" class="anchor" href="#takeaways"> 🔗 </a> Takeaways </h2> Here's what we've seen: <ul> <li>Components help you organize frontend code in ways that scale – conceptually and organizationally.</li> <li>Web Components offer a native way to build encapsulated, reusable user interfaces without needing a framework.</li> <li>UIElement builds on this foundation, simplifying common tasks like wiring inputs and syncing state to the DOM.</li> </ul> In short: you don't need a framework to build with components. You just need a few functions that stay close to the platform, while smoothing over the rough edges. </section> <section> <h2 id="coming-up-next-rethinking-reactivity"> <a name="coming-up-next-rethinking-reactivity" class="anchor" href="#coming-up-next-rethinking-reactivity"> 🔗 </a> Coming Up Next: Rethinking Reactivity </h2> In the next post, we'll revisit similar components and explore how reactivity can make more complex relationships easier to manage – like derived values, async state, and multiple sources of truth. We'll look at the pitfalls of imperative state wiring as logic grows, and how UIElement's signal graph provides a robust and minimal foundation for keeping your user interface in sync. Stay tuned! </section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2024 – 2025 Zeix AG </div> </footer> </context-router> </body> </html>