Anatomy of Components

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

Defining a Component

A UIElement creates components using the component() function:

component('my-component', {}, () => {
	// Component setup
})

Every UIElement component must be registered with a valid custom element tag name (two or more words joined with -) as the first parameter.

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

UIElement manages the Web Component lifecycle from creation to removal. Here's what happens.

Component Creation (constructor())

This is when reactive properties are initialized. You pass a second argument to the component() function to defines initial values for component states.

component('my-component', {
	count: 0, // Initial value of 'count' signal
	isEven: el => () => !(el.count % 2) // Computed signal based on 'count'
	value: asInteger(5), // Parse 'value' attribute as integer
	name: consume('display-name') // Consume 'display-name' signal from closest context provider
}, () => {
	// Component setup
})

In this example you see all 4 ways to define a reactive property:

• A static initial value for a State signal (e.g., count: 0)
• A signal producer that derives an initial value or a callback function from other properties of the element (e.g., isEven: el => () => !(el.count % 2))
• An attribute parser that may provide a fallback value (e.g., value: asInteger(5))
• A context consumer that emits a ContextRequestEvent (e.g., name: consume('display-name'))

Mounted in the DOM (connectedCallback())

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

• Access sub-elements
• Set up event listeners
• Apply effects
• Emit custom events
• Provide context

component('my-component', {
	count: 0,
}, el => {
	el.first('.increment', on('click', () => { el.count++ })) // Add click event listener
	el.first('.count', setText('count')) // Apply effect to update text
	el.self(
		emit('update-count', el.count) // Emit custom event
		provide('count') // Provide context
	)
})

Removed from the DOM (disconnectedCallback())

Runs when the component is removed. Event listeners bound with on() and signal subscriptions of effects are automatically removed by UIElement.

If you added event listeners outside the scope of your component or external subscriptions, you need to return a cleanup function:

component('my-component', {}, el => {
	const intersectionObserver = new IntersectionObserver(([entry]) => {
		// Do something
	}).observe(el)

	return () => {
		// Cleanup logic
		intersectionObserver.disconnect()
	}
})

Observed Attributes (attributeChangedCallback())

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

State Management with UIElement

UIElement manages state using signals, which are atomic reactive states that trigger updates when they change. We use regular properties to access or update them.

Accessing and Updating Signal Values

console.log('count' in el); // Check if the signal exists
console.log(el.count); // Read the signal value
el.count = 42; // Update the signal value

Accessing & Setting Signals Directly

If you need to access the signals for a property key directly, you can use the getSignal() and setSignal() methods:

const doubleString = el.getSignal('count').map(v => String(v * 2)); // Derive a new Computed signal from 'count' signal
el.querySelector('input-field').setSignal('description', doubleString); // Replace the signal on another element with a new one

However, you should avoid manipulating signals directly unless you have a specific reason to do so. Use the pass()function to pass a signal or a derivation thereof to other elements.

Characteristics and Special Values

Signals in UIElement are of a fixed type and non-nullable. This allows to simplify the logic as you will never have to check the type or perform null-checks.

• If you use TypeScript (recommended), you will be warned that null or undefined cannot be assigned to a signal or if you try to assign a value of a wrong type.
• If you use vanilla JavaScript without a build step, setting a signal to null or undefined will log an error to the console and abort. However, strict type checking is not enforced at runtime.

Because of the non-nullable nature of signals in UIElement, we need two special values that can be assigned to any signal type:

• RESET: Will reset to the server-rendered version that was there before UIElement took control. This is what you want to do most of the times when a signal lacks a specific value.
• UNSET: Will delete the signal, unsubscribe its watchers and also delete related attributes or style properties in effects. Use this with special care!

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

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

Pre-defined Parsers in UIElement

The pre-defined parsers asInteger(), asNumber() and asString() allow to set a custom fallback value as parameter.

The asEnum() parser requires an array of valid values, while the first will be the fallback value for invalid results.

The asJSON() parser requires a fallback object as parameter as {} probably won't match the type you're expecting.

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

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.

Single Component Example: MySlider

Bringing all of the above together, you are now ready to build your own components like this slider with prev / next buttons and dot indicators, demonstrating single-component reactivity.

Next Steps

Now that you understand the basics, explore:

• Styling Components – Learn techniques to apply styles to components.
• Data Flow – Learn about passing state between components.