🔗 How to Install UIElement

UIElement works without build tools but also supports package managers and bundlers for larger projects. Choose the option that best fits your needs.

🔗 Using a CDN

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.

<script src="https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js"></script>

🔗 Self-Hosting UIElement

For production use, you may want to self-host UIElement to avoid relying on a CDN. You can download the latest version from:

Github Repository

Simply host the file on your server and include it like this:

<script src="/path/to/your/hosted/ui-element.js"></script>

Why self-host?

• You control updates and avoid breaking changes from external CDNs.
• Works for projects with stricter Content Security Policy rules.

Remember to keep the hosted file updated to use the latest features and bug fixes.

🔗 Installing via Package Managers

If you're using a bundler like Vite, Webpack, or Rollup, install UIElement via NPM or Bun:

npm install @zeix/ui-element

bun add @zeix/ui-element

Then import the needed functions in your JavaScript:

import { asString, component, on, setText } from '@zeix/ui-element'

🔗 Creating Your First Component

Now, let's create an interactive Web Component to verify your setup.

What This Component Does

• Displays Hello, World! by default.
• Updates dynamically when you type into the input field.

🔗 Markup

Include the following in your server-rendered HTML:

<hello-world>
  <label>
    Your name<br />
    <input name="name" type="text" autocomplete="given-name" />
  </label>
  <p>Hello, <span>World</span>!</p>
</hello-world>

🔗 Component Definition

Save the following inside a <script type="module"> tag or an external JavaScript file.

<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>

🔗 Understanding Your First Component

This component demonstrates UIElement's core concepts:

• Reactive Properties: name: asString(...) creates a reactive property that syncs with the name attribute and falls back to the <span> content
• Effects: The setup function returns effects that handle user input and update the display text
• Element Selection: first() selects descendant elements to apply effects to

Learn more about these concepts in the Components guide.

🔗 Verifying Your Installation

If everything is set up correctly, you should see:

• A text input field
• A greeting (Hello, World!)
• The greeting updates as you type

If it's not working:

• Check the browser console for errors (missing imports, typos).
• Ensure your <script> tag is set to type="module" when using ES modules.
• If using NPM, confirm UIElement is installed inside node_modules/@zeix/ui-element.

🔗 Next Steps

You've successfully created your first reactive component! Now you're ready to dive deeper into UIElement's core concepts:

Next: Building Components
Learn the fundamental building blocks: component anatomy, element selection, basic state management, and event handling patterns.