@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="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.11.0</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>🚀 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>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>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> Or use <code><script type="module"></code> to import UIElement in your 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><script type="module"> import { UIElement } from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js' // Your code here </script> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <ul> <li>✅ No build step required</li> <li>✅ Works with any server-rendered HTML</li> <li>✅ Automatic hydration when components are dynamically inserted</li> </ul> </section> <section> <h3>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>Installing via NPM</h3> If you’re using a bundler like Vite, Webpack, or Rollup, install UIElement via 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> Then import <code>UIElement</code> 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 { UIElement } from '@zeix/ui-element' </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <ul> <li>✅ Best for larger projects using a build pipeline</li> <li>✅ Works with modern JavaScript/TypeScript tooling</li> </ul> </section> <section> <h2>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>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>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 { UIElement, setText, RESET } from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js' class HelloWorld extends UIElement { static localName = 'hello-world'; connectedCallback() { // Update content dynamically based on the 'name' signal this.first('span').sync(setText('name')); // Handle user input to change the 'name' this.first('input').on('input', e => { this.set('name', e.target.value || RESET) }); } } HelloWorld.define(); </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>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, falling back to the initial value if empty with (constant <code>RESET</code>).</li> <li>✅ The Web Component hydrates automatically when inserted into the page.</li> </ul> </section> <section> <h2>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>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> © 2025 Zeix AG </div> </footer> </body> </html>