@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>Getting Started – UIElement Docs</title> <meta name="description" content="Installation, setup, and first steps" /> <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="getting-started"> <a name="getting-started" class="anchor" href="#getting-started"> 🔗 🚀 Getting Started </a> </h1> <div> Set up UIElement in minutes – no build tools required. Or use any package manager and bundler to take advantage of TypeScript support and optimize frontend assets. <module-toc> <nav> <h2>In This Page</h2> <ol> <li><a href="#how-to-install-uielement">How to Install UIElement</a></li> <li><a href="#creating-your-first-component">Creating Your First Component</a></li> <li><a href="#verifying-your-installation">Verifying Your Installation</a></li> <li><a href="#next-steps">Next Steps</a></li> </ol> </nav> </module-toc> </div> </section-hero> <section> <h2 id="how-to-install-uielement"> <a name="how-to-install-uielement" class="anchor" href="#how-to-install-uielement"> 🔗 How to Install UIElement </a> </h2> UIElement works without build tools but also supports package managers and bundlers for larger projects. Choose the option that best fits your needs. <h3 id="using-a-cdn"> <a name="using-a-cdn" class="anchor" href="#using-a-cdn"> 🔗 Using a CDN </a> </h3> For the easiest setup, include UIElement via a CDN. This is ideal for testing or quick projects where you want lightweight interactivity without additional tooling. <module-codeblock language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> page.html html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><script src="https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js"></script> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> </section> <section> <h3 id="self-hosting-uielement"> <a name="self-hosting-uielement" class="anchor" href="#self-hosting-uielement"> 🔗 Self-Hosting UIElement </a> </h3> For production use, you may want to self-host UIElement to avoid relying on a CDN. You can download the latest version from: <a href="https://github.com/zeixcom/ui-element/blob/main/index.js" target="_blank">Github Repository</a> Simply host the file on your server and include it like this: <module-codeblock language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> page.html html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><script src="/path/to/your/hosted/ui-element.js"></script> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> Why self-host? <ul> <li>You control updates and avoid breaking changes from external CDNs.</li> <li>Works for projects with stricter Content Security Policy rules.</li> </ul> Remember to keep the hosted file updated to use the latest features and bug fixes. </section> <section> <h3 id="installing-via-package-managers"> <a name="installing-via-package-managers" class="anchor" href="#installing-via-package-managers"> 🔗 Installing via Package Managers </a> </h3> If you're using a bundler like Vite, Webpack, or Rollup, install UIElement via NPM or Bun: <module-tabgroup> <div role="tablist"> <button role="tab" id="trigger_installation-npm" aria-controls="panel_installation-npm" aria-selected="true" tabindex="0">NPM</button> <button role="tab" id="trigger_installation-bun" aria-controls="panel_installation-bun" aria-selected="false" tabindex="-1">Bun</button> </div> <div role="tabpanel" id="panel_installation-npm" aria-labelledby="trigger_installation-npm"> <module-codeblock language="sh" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> $ sh <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>npm install @zeix/ui-element </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> </div> <div role="tabpanel" id="panel_installation-bun" aria-labelledby="trigger_installation-bun"> <module-codeblock language="sh" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> $ sh <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>bun add @zeix/ui-element </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> </div> </module-tabgroup> Then import the needed functions in your JavaScript: <module-codeblock language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> main.js js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>import { asString, component, on, setText } from '@zeix/ui-element' </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> </section> <section> <h2 id="creating-your-first-component"> <a name="creating-your-first-component" class="anchor" href="#creating-your-first-component"> 🔗 Creating Your First Component </a> </h2> Now, let's create an interactive Web Component to verify your setup. What This Component Does <ul> <li>Displays <code>Hello, World!</code> by default.</li> <li>Updates dynamically when you type into the input field.</li> </ul> <h3 id="markup"> <a name="markup" class="anchor" href="#markup"> 🔗 Markup </a> </h3> Include the following in your server-rendered HTML: <module-codeblock language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> page.html html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><hello-world> <label> Your name<br /> <input name="name" type="text" autocomplete="given-name" /> </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> <h3 id="component-definition"> <a name="component-definition" class="anchor" href="#component-definition"> 🔗 Component Definition </a> </h3> Save the following inside a <code><script type="module"></code> tag or an external JavaScript file. <module-codeblock collapsed language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> page.html html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><script type="module"> import { asString, component, on, setText, } from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js' 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')), ] }, ) </script> </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="understanding-your-first-component"> <a name="understanding-your-first-component" class="anchor" href="#understanding-your-first-component"> 🔗 Understanding Your First Component </a> </h3> This component demonstrates UIElement's core concepts: <ul> <li>Reactive Properties: <code>name: asString(...)</code> creates a reactive property that syncs with the <code>name</code> attribute and falls back to the <code></code> content</li> <li>Effects: The setup function returns effects that handle user input and update the display text</li> <li>Element Selection: <code>first()</code> selects descendant elements to apply effects to</li> </ul> Learn more about these concepts in the <a href="components.html">Components</a> guide. </section> <section> <h2 id="verifying-your-installation"> <a name="verifying-your-installation" class="anchor" href="#verifying-your-installation"> 🔗 Verifying Your Installation </a> </h2> If everything is set up correctly, you should see: <ul> <li>A text input field</li> <li>A greeting (<code>Hello, World!</code>)</li> <li>The greeting updates as you type</li> </ul> <module-demo> <div class="preview"> <hello-world> <label>Your name <input name="name" type="text" autocomplete="given-name"> </label> Hello, World! </hello-world> </div> </module-demo> If it's not working: <ul> <li>Check the browser console for errors (missing imports, typos).</li> <li>Ensure your <code><script></code> tag is set to <code>type="module"</code> when using ES modules.</li> <li>If using NPM, confirm UIElement is installed inside <code>node_modules/@zeix/ui-element</code>.</li> </ul> </section> <section> <h2 id="next-steps"> <a name="next-steps" class="anchor" href="#next-steps"> 🔗 Next Steps </a> </h2> You've successfully created your first reactive component! Now you're ready to dive deeper into UIElement's core concepts: Next: Building <a href="components.html">Components</a> Learn the fundamental building blocks: component anatomy, element selection, basic state management, and event handling patterns. </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>