Anatomy of a UIElement Component

UIElement builds on Web Components, extending HTMLElement to provide built-in state management and reactive updates.

Defining a Component

A UIElement component is created by extending UIElement:

class MyComponent extends UIElement {
	/* component definition */
}

Registering a Custom Element

Every UIElement component must be registered with a valid custom tag name (two or more words joined with -) using .define().

MyComponent.define('my-component');

Using the Custom Element in HTML

Once registered, the component can be used like any native HTML element:

<my-component>Content goes here</my-component>

Web Component Lifecycle in UIElement

Every UIElement component follows a lifecycle from creation to removal. Here’s how the key lifecycle methods work:

Component Creation (constructor())

Runs when the element is created but before it’s attached to the DOM. Avoid accessing attributes or child elements here.

Mounted in the DOM (connectedCallback())

Runs when the component is added to the page. This is where you:

• ✅ Initialize state
• ✅ Set up event listeners
• ✅ Apply effects

class MyComponent extends UIElement {
	connectedCallback() {
		this.first('.increment').on('click', () => { // Add click event listener
			this.set('count', v => null != v ? ++v : 1)
		});
		this.first('.count').sync(setText('count')); // Apply effect to update text
	}
}

Removed from the DOM (disconnectedCallback())

Runs when the component is removed. Use this to clean up event listeners or external subscriptions.

Observed Attributes (attributeChangedCallback())

UIElement automatically converts attributes to reactive signals. Usually, you don’t need to override this method manually.

State Management with UIElement

UIElement manages state using signals, which are reactive values that trigger updates when they change. We use a familiar Map-like API:

Defining & Using Signals

this.set('count', 0); // Create a state signal
this.set('isEven', () => !((this.get('count') ?? 0) % 2)); // Create a derived signal

Checking & Removing Signals

if (this.has('count')) { /* Do something */ }
this.delete('count'); // Removes the signal and its dependencies

Why Signals with a Map Interface?

UIElement uses signals instead of standard properties or attributes because it ensures reactivity, loose coupling, and avoids common pitfalls with the DOM API.

• ✅ Signals enable loose coupling between components: A component that modifies state doesn’t need to know which or how many elements depend on that state. Any UI updates happen automatically wherever that signal is used.
• ✅ Signals trigger automatic updates: Any DOM element or effect that depends on a signal updates itself when the signal changes. The source doesn't need to know how the updated state should change the DOM.
• ✅ Standard JavaScript properties are not reactive: JavaScript properties don’t automatically trigger updates when changed. The distinct Map-like interface avoids confusion.
• ✅ Attributes can only store strings: Attributes in HTML are always strings. If you store numbers, booleans, or objects, you must manually convert them between string format and usable values. Signals avoid this extra conversion step.
• ✅ The Map interface avoids name conflicts:
  • The HTMLElement namespace is crowded, meaning using direct properties can accidentally override existing methods or properties.
  • HTML attributes are kebab-case (data-user-id), but JavaScript properties are camelCase (dataUserId), which can cause inconsistencies.
  • With a Map, we can use attributes names directly as state keys (e.g., "count" or "is-active") without conversion or worrying about naming conflicts.

Initializing State from Attributes

Declaring Observed Attributes

static observedAttributes = ['count']; // Automatically becomes a signal

Parsing Attribute Values

static states = {
	count: asInteger, // Convert '42' -> 42
	date: v => new Date(v), // Custom parser: '2025-02-14' -> Date object
};

Pre-defined Parsers in UIElement

Accessing Sub-elements within the Component

Before adding event listeners, applying effects, or passing states, you need to select elements inside the component.

UIElement provides the following methods for element selection:

// Select the component itself
this.self.sync(setProperty('hidden'));

// Select the first '.increment' button & add a click event
this.first('.increment').on('click', () => {
	this.set('count', v => null != v ? ++v : 1);
});

// Select all <button> elements & sync their 'disabled' properties
this.all('button').sync(setProperty('disabled', 'hidden'));

Updating State with Events

User interactions should update signals, not the DOM directly. This keeps the components loosly coupled.

Bind event handlers to one or many elements using the .on() method:

this.first('.increment').on('click', () => {
	this.set('count', v => null != v ? v++ : 1)
});
this.first('input').on('input', e => {
	this.set('name', e.target.value || undefined)
});

Synchronizing State with Effects

Effects automatically update the DOM when signals change, avoiding manual DOM manipulation.

Applying Effects with .sync()

Apply one or multiple effects to elements using .sync():

this.first('.count').sync(
	setText('count'), // Update text content according to 'count' signal
	toggleClass('even', 'isEven') // Toggle 'even' class according to 'isEven' signal
);

Pre-defined Effects in UIElement

Simplifying Effect Notation

For effects that take two arguments, the second argument can be omitted if the signal key matches the targeted property name, attribute, class, or style property.

When signal key matches property name:

this.first('.count').sync(toggleClass('even'));

Here, toggleClass('even') automatically uses the "even" signal.

Using Functions for Ad-hoc Derived State

Instead of a signal key, you can pass a function that derives a value dynamically:

this.first('.count').sync(toggleClass('even', () => !((this.get('count') ?? 0) % 2)));

When to Use a Function Instead of a Signal Key?

• Use a signal key when the state is already stored as a signal.
• Use a function when you derive the value on the fly that you need only in one place and you don't want to expose it as a signal on the element.

Custom Effects

For complex DOM manipulations, define your own effect using effect().

Here's an example effect that attaches a Shadow DOM and updates its content:

// Update the shadow DOM when content changes
effect(() => {
	const content = this.get('content')
	if (content) {
		this.root = this.shadowRoot || this.attachShadow({ mode: 'open' })
		this.root.innerHTML = content
	}
});

Efficient & Fine-Grained Updates

Unlike some frameworks that re-render entire components, UIElement updates only what changes:

• ✅ No virtual DOM – UIElement modifies the DOM directly.
• ✅ Signals propagate automatically – No need to track dependencies manually.
• ✅ Optimized with a scheduler – Multiple updates are batched efficiently.

In practical terms: UIElement is as easy as React but without re-renders.

Next Steps

Now that you understand the basics, explore:

• Detailed Walkthrough – Hands-on guide to creating a UIElement component.
• Best Practices & Patterns – Learn about structuring components and passing state between components.