@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>UIElement – UIElement Docs</title> <meta name="description" content="" /> <link rel="stylesheet" href="../assets/main.css" /> <script type="module" src="../assets/main.js"></script> </head> <body class="api"> <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 class="api-content"> <h1 id="uielement"> <a name="uielement" class="anchor" href="#uielement"> 🔗 </a> UIElement </h1> Version 0.13.3 UIElement - a HTML-first library for reactive Web Components UIElement is a set of functions to build reusable, loosely coupled Web Components with reactive properties. It provides structure through components and simplifies state management and DOM synchronization using declarative signals and effects, leading to more organized and maintainable code without a steep learning curve. Unlike SPA frameworks (React, Vue, Svelte, etc.) UIElement takes a HTML-first approach, progressively enhancing sever-rendered HTML rather than recreating (rendering) it using JavaScript. UIElement achieves the same result as SPA frameworks with SSR, but with a simpler, more efficient approach. It works with a backend written in any language or with any static site generator. <h2 id="key-features"> <a name="key-features" class="anchor" href="#key-features"> 🔗 </a> Key Features </h2> <ul> <li>🧱 HTML Web Components: Build on standard HTML and enhance it with encapsulated, reusable Web Components. No virtual DOM – UIElement works directly with the real DOM.</li> <li>🚦 Reactive Properties: Define reactive properties for fine-grained, efficient state management (signals). Changes automatically propagate only to the parts of the DOM that need updating, avoiding unnecessary re-renders.</li> <li>🧩 Function Composition: Declare component behavior by composing small, reusable functions (attribute parsers and effects). This promotes cleaner code compared to spaghetti code problems that commonly occur when writing low-level imperative code.</li> <li>🛠️ Customizable: UIElement is designed to be easily customizable and extensible. You can create your own custom attribute parsers and effects to suit your specific needs.</li> <li>🌐 Context Support: Share global states across components without prop drilling or tightly coupling logic.</li> <li>🪶 Tiny footprint: Minimal core (~4kB gzipped) with tree-shaking support, adding only the necessary JavaScript to enhance your HTML.</li> <li>🛡️ Type Safety: Get early warnings when types don't match, improving code quality and reducing bugs.</li> </ul> UIElement uses <a href="https://github.com/zeixcom/cause-effect">Cause & Effect</a> internally for state management with signals and for scheduled DOM updates. But you could easily rewrite the <code>component()</code> function to use a signals library of your choice or to produce something else than Web Components. <h2 id="installation"> <a name="installation" class="anchor" href="#installation"> 🔗 </a> Installation </h2> <module-codeblock language="bash" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> bash <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code># with npm npm install @zeix/ui-element # or with bun bun add @zeix/ui-element </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h2 id="documentation"> <a name="documentation" class="anchor" href="#documentation"> 🔗 </a> Documentation </h2> The full documentation is still work in progress. The following chapters are already reasonably complete: <ul> <li><a href="https://zeixcom.github.io/ui-element/index.html">Introduction</a></li> <li><a href="https://zeixcom.github.io/ui-element/getting-started.html">Getting Started</a></li> <li><a href="https://zeixcom.github.io/ui-element/components.html">Components</a></li> <li><a href="https://zeixcom.github.io/ui-element/styling.html">Styling</a></li> <li><a href="https://zeixcom.github.io/ui-element/data-flow.html">Data Flow</a></li> <li><a href="https://zeixcom.github.io/ui-element/about.html">About</a></li> </ul> <h2 id="basic-usage"> <a name="basic-usage" class="anchor" href="#basic-usage"> 🔗 </a> Basic Usage </h2> <h3 id="counter"> <a name="counter" class="anchor" href="#counter"> 🔗 </a> Counter </h3> Server-rendered markup: <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><basic-counter count="5"> <button type="button">💐 <span>5</span></button> </basic-counter> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> UIElement component: <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 { asInteger, component, on, setText } from '@zeix/ui-element' export default component( 'basic-counter', { count: asInteger(), // Get initial value from count attribute }, (el, { first }) => [ // Update count display when state changes first('span', setText('count')), // Handle click events to change state 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> Example styles: <module-codeblock collapsed 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>basic-counter { & button { border: 1px solid var(--color-border); border-radius: var(--space-xs); background-color: var(--color-secondary); padding: var(--space-xs) var(--space-s); cursor: pointer; color: var(--color-text); font-size: var(--font-size-m); line-height: var(--line-height-xs); transition: background-color var(--transition-short) var(--easing-inout); &:hover { background-color: var(--color-secondary-hover); } &:active { background-color: var(--color-secondary-active); } } } </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="tab-group"> <a name="tab-group" class="anchor" href="#tab-group"> 🔗 </a> Tab Group </h3> An example demonstrating how to create a fully accessible tab navigation. Server-rendered markup: <module-codeblock collapsed 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><module-tabgroup> <div role="tablist"> <button type="button" role="tab" id="trigger1" aria-controls="panel1" aria-selected="true" tabindex="0" > Tab 1 </button> <button type="button" role="tab" id="trigger2" aria-controls="panel2" aria-selected="false" tabindex="-1" > Tab 2 </button> <button type="button" role="tab" id="trigger3" aria-controls="panel3" aria-selected="false" tabindex="-1" > Tab 3 </button> </div> <div role="tabpanel" id="panel1" aria-labelledby="trigger1"> Tab 1 content </div> <div role="tabpanel" id="panel2" aria-labelledby="trigger2" hidden> Tab 2 content </div> <div role="tabpanel" id="panel3" aria-labelledby="trigger3" hidden> Tab 3 content </div> </module-tabgroup> </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> UIElement component: `js export const manageArrowKeyFocus = (elements, index) => e => { if (!(e instanceof KeyboardEvent)) throw new TypeError('Event is not a KeyboardEvent') const handledKeys = [ 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', ] if (handledKeys.includes(e.key)) { e.preventDefault() switch (e.key) { case 'ArrowLeft': case 'ArrowUp': index = index < 1 ? elements.length - 1 : index - 1 break case 'ArrowRight': case 'ArrowDown': index = index >= elements.length - 1 ? 0 : index + 1 break case 'Home': index = 0 break case 'End': index = elements.length - 1 break } if (elements[index]) elements[index].focus() } } <pre><code> Example styles: ### Lazy Load An example demonstrating how to use a custom attribute parser (sanitize an URL) and a signal producer (async fetch) to implement lazy loading. UIElement component: Custom attribute parser: ## Contributing & License Feel free to contribute, report issues, or suggest improvements. License: [MIT](_media/LICENSE) (c) 2025 [Zeix AG](https://zeix.com) </code></pre> </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>