🔗 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 { component, on, RESET, 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 type="text" />
  </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,
    RESET,
    setText,
  } from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js'

  component(
    'hello-world',
    {
      // Fall back to server-rendered content
      name: asString(RESET),
    },
    (el, { first }) => [
      // 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>

What Happens Here?

• The name: RESET property gets its initial value from the server-rendered content (the <span> text).
• The setText('name') effect syncs the state with the <span>.
• The on('input') event updates the state whenever you type in the first <input> field, falling back to server-rendered value if empty.
• The Web Component hydrates automatically when inserted into the page.

🔗 Understanding Your First Component

Let's break down each part of your <hello-world> component to understand how UIElement works:

🔗 Reactive Properties

{
  name: RESET
}

This creates a reactive property called name:

• RESET means "use whatever text is already in the HTML" as the starting value
• UIElement automatically reads "World" from the <span> element as the initial value
• When name changes, any effects that depend on it automatically update

There are other ways to initialize state in UIElement. You'll learn about those approaches in the section about components.

🔗 Setup Function

Returns an array of effects:

(el, { first }) => [
  first('span', setText('name')),
  first('input', on('input', e => { ... }))
]

Effects define component behaviors:

• first('span', setText('name')) finds the first <span> and keeps its text in sync with the name property
• first('input', on('input', ...)) finds the first <input> and adds an event listener

Characteristics of Effects:

• Effects run when the component is added to the page
• Effects rerun when their dependencies change
• Effects may return a cleanup function to be executed when the component is removed from the page

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