@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" /> <base href="./getting-started.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" class="active"> 🚀 Getting Started Installation, setup, and first steps </a> </li> <li> <a href="building-components.html"> 🏗️ 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="getting-started"> <a name="getting-started" class="anchor" href="#getting-started"> 🔗 </a> 🚀 Getting Started </h1>Set up UIElement in minutes – no build tools required. Whether you’re enhancing server-rendered HTML with lightweight interactivity or integrating Web Components into a modern JavaScript project, UIElement makes it simple to get started. </section> <section> <h2 id="how-to-install-uielement"> <a name="how-to-install-uielement" class="anchor" href="#how-to-install-uielement"> 🔗 </a> How to Install UIElement </h2>UIElement works without build tools but also supports NPM and module 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"> 🔗 </a> Using a CDN </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. <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><script src="https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js"></script> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </section> <section> <h3 id="self-hosting-uielement"> <a name="self-hosting-uielement" class="anchor" href="#self-hosting-uielement"> 🔗 </a> Self-Hosting UIElement </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: <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><script src="/path/to/your/hosted/ui-element.js"></script> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> 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"> 🔗 </a> Installing via Package Managers </h3>If you’re using a bundler like Vite, Webpack, or Rollup, install UIElement via NPM or Bun: <tab-group> <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"> <code-block 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>npm install @zeix/ui-element </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </div> <div role="tabpanel" id="panel_installation-bun" aria-labelledby="trigger_installation-bun"> <code-block 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>bun add @zeix/ui-element </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </div> </tab-group> Then import the needed functions in your JavaScript: <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>import { asString, component, first, on, RESET, setText } from '@zeix/ui-element' </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> </section> <section> <h2 id="creating-your-first-component"> <a name="creating-your-first-component" class="anchor" href="#creating-your-first-component"> 🔗 </a> Creating Your First Component </h2>Now, let's create an interactive Web Component to verify your setup. What This Component Does <ul> <li>Displays “Hello, World!” 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"> 🔗 </a> Markup </h3>Include the following in your server-rendered HTML: <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><hello-world> <label>Your name<br> <input type="text"> </label> <p>Hello, <span>World</span>!</p> </hello-world> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3 id="component-definition"> <a name="component-definition" class="anchor" href="#component-definition"> 🔗 </a> Component Definition </h3>Save the following inside a <code><script type="module"></code> tag or an external JavaScript file. <code-block 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><script type="module"> import { asString, component, first, on, RESET, setText } from "https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js" component("hello-world", { // Parse "name" attribute, falling back to server-rendered content name: asString(RESET) }, el => [ // Update content dynamically based on the "name" signal first("span", setText("name")), // Handle user input to change the "name" first("input", on("input", e => { el.name = e.target.value || RESET })) ]) </script> </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> What Happens Here? <ul> <li>The <code>asString(RESET)</code> signal parses the "name" attribute, falling back to server-rendered value (constant <code>RESET</code>).</li> <li>The <code>setText('name')</code> effect syncs the state with the <code></code>.</li> <li>The <code>on('input')</code> event updates the state whenever you type in the first <code><input></code> field, falling back to server-rendered value if empty.</li> <li>The Web Component hydrates automatically when inserted into the page.</li> </ul> </section> <section> <h2 id="verifying-your-installation"> <a name="verifying-your-installation" class="anchor" href="#verifying-your-installation"> 🔗 </a> Verifying Your Installation </h2>If everything is set up correctly, you should see: <ul> <li>A text input field</li> <li>A greeting (Hello, World!)</li> <li>The greeting updates as you type</li> </ul> <component-demo> <div class="preview"> <hello-world> <template shadowrootmode="open"> <label>Your name <input type="text"> </label> Hello, World! </template> </hello-world> </div> </component-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"> 🔗 </a> Next Steps </h2>Now that UIElement is installed, explore the core concepts for <a href="building-components.html">Building Components</a>: <ul> <li>✅ Component anatomy and lifecycle (using Web Components)</li> <li>✅ Accessing sub-elements (select children)</li> <li>✅ Signals & effects (state-driven DOM updates)</li> <li>✅ Event listeners (react to user interaction)</li> </ul> Or jump straight to <a href="styling-components.html">Styling Components</a> for CSS best practices. </section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2024 – 2025 Zeix AG </div> </footer> </body> </html>