π π Getting Started
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.
π How to Install UIElement
UIElement works without build tools but also supports NPM and module 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:
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, first, 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, 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>
What Happens Here?
- The
asString(RESET)
signal parses the "name" attribute, falling back to server-rendered value (constantRESET
). - 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.
π 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
Hello, World!
If it's not working:
- Check the browser console for errors (missing imports, typos).
- Ensure your
<script>
tag is set totype="module"
when using ES modules. - If using NPM, confirm UIElement is installed inside
node_modules/@zeix/ui-element
.
π Next Steps
Now that UIElement is installed, explore the core concepts for Building Components:
- β Component anatomy and lifecycle (using Web Components)
- β Accessing sub-elements (select children)
- β Signals & effects (state-driven DOM updates)
- β Event listeners (react to user interaction)
Or jump straight to Styling Components for CSS best practices.