Core FoundationsInteractivity

Interactivity #

WebUI uses Islands Architecture for client-side interactivity. Each Web Component is a self-contained island with its own HTML template, authored CSS, and TypeScript behavior. Shadow components provide CSS isolation; Light components intentionally participate in the owning CSS tree's global cascade. Only components that need interactivity ship JavaScript - everything else stays as static server-rendered HTML.

Component Files #

Every interactive component consists of three separate files. Templates are declarative - no JavaScript mixing.

my-counter/
├── my-counter.html   ← Template (structure and bindings)
├── my-counter.css    ← Authored styles
└── my-counter.ts     ← Behavior (TypeScript class)
  • HTML defines what the component renders and where dynamic values appear
  • CSS styles the component. Light DOM uses the owning tree's global cascade; Shadow components use the browser's native boundary
  • TypeScript defines JS-visible reactive properties, event handlers, and component logic

Components that do not need client-side behavior can omit the TypeScript file:

product-card/
├── product-card.html
└── product-card.css

Create a custom element only for an Interactive Island: event handlers, custom lifecycle code, imperative methods, or state that TypeScript code reads or mutates. @observable and @attr are optional; add them when JavaScript needs to access the value or when the value is part of the component's public API.

The sibling .ts or .js file is the authored behavior boundary. With manifest-enabled projection, only @observable and @attr fields opt into initial state hydration; ordinary template roots remain in the trusted SSR DOM. Without a client module, bindings, conditionals, and loops still render on the server, but the component contributes no projected keys. If the framework is loaded, it can later activate the compiled template for browser-applied state or soft navigation. Without any projection manifest, the server preserves full state. Add a same-named client module only for events, lifecycle code, decorators, or imperative APIs. See Hydration for the full contract.

The Component Class #

Every interactive component extends WebUIElement and registers itself as a custom element:

import { WebUIElement, attr, observable } from '@microsoft/webui-framework';

export class MyCounter extends WebUIElement {
  @attr label = 'Count';
  @observable count = 0;

  increment(): void {
    this.count += 1;
  }
}

MyCounter.define('my-counter');

For a component repeated far beyond the initial viewport, put the complete offscreen policy on its root template:

<!-- todo-row.html -->
<template w-render="lazy" w-reserve-block-size="72px">
  <!-- Component content -->
</template>

Import the optional coordinator once before component registration modules:

import '@microsoft/webui-framework/lazy-hydration.js';
import './todo-row.js';

The complete policy composes visibility-deferred hydration with content-visibility: auto. Use <template w-hydrate="lazy"> for the advanced hydration-only policy. On an instance, w-hydrate="eager" keeps rendering deferral but hydrates immediately, while w-render="eager" disables both. Put setup that needs bindings, events, or w-ref in hydratedCallback().

See Lazy Hydration.

The matching template (my-counter.html):

<button @click="{increment()}">
  {{label}}: {{count}}
</button>

And authored Light DOM styles (my-counter.css):

my-counter {
  display: inline-block;
}

button {
  padding: 0.5rem 1rem;
  font-size: 1rem;
  cursor: pointer;
}

The <template> Tag #

Unwrapped components default to Shadow DOM. Build with --dom light to render unwrapped content directly into the component host.

A sole bare top-level <template> explicitly selects Light DOM and is unwrapped even when the build fallback is Shadow. A template with attributes or w-render/w-hydrate is not a mode selector; nested templates remain ordinary inert template content.

Light DOM (--dom light):

<!-- my-counter.html -->
<button @click="{increment()}">{{label}}: {{count}}</button>

The paired CSS remains authored/global in the owning CSS tree. Use ordinary selectors such as my-counter; Shadow-only :host and ::slotted selectors fail in effective Light CSS.

Authored Shadow island (including inside a Light build):

<!-- todo-app.html -->
<template shadowrootmode="open"
  @toggle-item="{onToggleItem(e)}"
  @delete-item="{onDeleteItem(e)}"
>
  <h1>{{title}}</h1>
  <div class="todo-list">
    <for each="item in items">
      <todo-item id="{{item.id}}" title="{{item.title}}"></todo-item>
    </for>
  </div>
</template>

The open template must be the sole top-level element and wrap the complete component. Use it when the component needs native <slot> composition, a native Shadow boundary, or root host events - listeners on the component root that catch events bubbling up from child components (@toggle-item, @delete-item above). closed, another value, invalid placement, multiple wrappers, or extra top-level content fails the build. A native <slot> fails only when the component's effective mode is Light.

To reach a root binding from a child component, an event must bubble and be composed whenever any Shadow boundary exists between the child and the listener. this.$emit() always sets both, including for a Light component nested in another component's Shadow tree. A hand-built new CustomEvent('my-event') defaults to neither and will never arrive - bind it on the child element instead, or pass { bubbles: true, composed: true } yourself.

A root binding lives on the host element, so it also catches events targeted at the host itself - what host-interactive components (host tabindex, presentational shadow content) rely on. It does not see non-composed events (change, submit, select, media events), which stop at the shadow boundary because they identify one specific inner element; bind those per element - <input @change="{onChange(e)}">.

Since the listener is on the host, e.target is the host for events raised inside the shadow tree. Use e.composedPath()[0] to get the element that was actually hit.

Decorators define how properties behave and how they connect to the template.

@attr - HTML Attributes #

Use @attr for values passed from a parent element via HTML attributes. These are part of the component's public API.

String mode (default):

@attr label = 'Default Label';

<my-counter label="Items"></my-counter>

Boolean mode - attribute presence means true, absence means false:

@attr({ mode: 'boolean' }) disabled = false;

<!-- disabled = true -->
<my-button disabled></my-button>

<!-- disabled = false -->
<my-button></my-button>

When build-time projection is enabled, @attr property names are included in initial state metadata. If SSR already emitted the corresponding host attribute, that attribute is authoritative during hydration. Projected state fills the property only when the host attribute is absent.

@observable - Reactive State #

Use @observable for internal state that changes over time. When an observable value changes, the framework automatically updates any template bindings that reference it.

@observable count = 0;
@observable items: Item[] = [];
@observable isOpen = false;

Observable changes are synchronous and targeted - only the specific DOM nodes bound to the changed property are updated.

You do not need @observable for values that are only read by the template. Add @observable when TypeScript code needs to read or mutate the value, for example in an event handler.

Initial Hydration State #

For the initial page, build-time projection can narrow state to top-level @observable and @attr values from authored components. Template bindings still render on the server, but they do not automatically become JavaScript state. Only components reachable on the active route contribute projected values. Without a projection manifest, WebUI intentionally sends full state.

See Hydration for HTML-only components, soft navigation, and payload behavior.

Derived State #

For derived values like "has items?" or "total count", use template expressions directly instead of computed properties:

<!-- Use dot-path expressions in the template -->
<if condition="items.length">
  <span>{{items.length}} items</span>
</if>

The condition evaluator supports dot paths (items.length), comparisons (count > 0), truthiness, and negation (!isEmpty). This keeps derived state declarative and works on both server and client.

For complex derived state that can't be expressed in template syntax, compute it on the server and provide it in the JSON state, or compute it in an event handler and store it in an @observable.

Template Syntax for Interactivity #

Reactive Text #

Use double curly braces to bind property values into the template:

<span>{{label}}: {{count}}</span>
<p>Hello, {{user.name}}!</p>

Event Binding #

Attach event handlers with @event syntax:

<!-- Call a method -->
<button @click="{increment()}">Add</button>

<!-- Access the event object -->
<input @keydown="{onKeydown(e)}" />

<!-- Pass repeat-scope values and literals -->
<for each="item in items">
  <button @click="{selectItem(item.id, 'details', e)}">
    {{item.name}}
  </button>
</for>

<!-- Multiple events on one element -->
<div @mouseenter="{onHover()}" @mouseleave="{onLeave()}">
  Hover me
</div>

Components that use @event must have authored .ts or .js code that defines a WebUIElement for the tag. HTML-only components do not provide application event handlers.

Event handlers use method-call syntax only. Arguments can be:

  • e for the native DOM event
  • Dotted component or repeat-scope paths such as item.id
  • String, number, boolean, and null literals

General JavaScript expressions and nested function calls are not parsed in templates. Compute those values in the component class or pass a supported path.

Invalid handler syntax, such as a general expression like @click="e.preventDefault()" or a bare name like @click="{closeMenu}", fails the build with an actionable error that names the offending component and element.

DOM References #

Use w-ref to get a direct reference to a DOM element:

<input w-ref="{inputEl}" type="text" />
<button @click="{focusInput()}">Focus</button>

inputEl!: HTMLInputElement;

focusInput(): void {
  this.inputEl.focus();
}

w-ref must use braces to bind to a component property: w-ref="{inputEl}" (or the unquoted w-ref={inputEl}), never w-ref="inputEl". The build fails with an actionable error otherwise.

w-ref is scalar. Reusing a name inside <for> writes the same property, so the last wired occurrence wins; repeat keys and positions do not create an indexed ref collection. For lookup by item identity, author a stable id and use the owning document or shadow root's getElementById(), or move the ref into an item component.

Conditional Rendering #

Render content based on expressions:

<if condition="count > 0">
  <p>You have {{count}} items.</p>
</if>

<if condition="!isLoggedIn">
  <a href="/login">Sign in</a>
</if>

Boolean Attributes #

Toggle HTML attributes with the ? prefix:

<button ?disabled="{{isLoading}}">Submit</button>
<input ?checked="{{isSelected}}" type="checkbox" />
<details ?open="{{isExpanded}}">...</details>

Property Bindings #

Use the : prefix to pass rich values directly to child DOM properties:

<profile-card :config="{{settings}}"></profile-card>

For client-created component trees, WebUI applies initial property bindings before child connectedCallback methods run. This lets a child read a parent-provided property during setup. If the parent has not provided a value, the child can initialize a fallback in connectedCallback; later parent updates still flow through the live binding.

List Rendering #

Iterate over arrays with <for>:

<ul>
  <for each="item in items">
    <li>{{item.name}} - {{item.price}}</li>
  </for>
</ul>

Event Handling Patterns #

Direct Method Calls #

The simplest pattern - call a method when an event fires:

@observable count = 0;

increment(): void {
  this.count += 1;
}

<button @click="{increment()}">+1</button>

Using the Event Object #

Access the native DOM event by passing e:

onKeydown(e: KeyboardEvent): void {
  if (e.key === 'Enter') {
    this.submit();
  }
}

<input @keydown="{onKeydown(e)}" />

Passing Values from Repeats #

Handlers inside a <for> block can receive the current item through a dotted path. The framework captures the active repeat scope during hydration and resolves the argument when the event fires:

selectItem(id: string, e: MouseEvent): void {
  e.preventDefault();
  this.selectedId = id;
}

<for each="item in items">
  <button @click="{selectItem(item.id, e)}">
    {{item.title}}
  </button>
</for>

How Event Bindings Are Wired #

Every @event gets its own listener on the element it is written on. Bindings are never delegated to a shared root listener, which has two consequences worth knowing:

  • Non-bubbling events work. @focus, @blur, @mouseenter, @load, @error, and @toggle fire normally. A shared root listener could never see them, because those events do not travel up the tree.
  • stopPropagation() behaves as written. An ancestor stopping an event as it bubbles cannot suppress a handler bound to the element the event started on.

Dispatch cost does not grow with the number of rows a <for> renders. If you do want a single listener instead of one per row for a very long list, use root host events and find the row yourself with e.composedPath().

Custom Events and Parent-Child Communication #

Components communicate upward by emitting custom events with this.$emit():

Child component (color-picker.ts):

export class ColorPicker extends WebUIElement {
  @observable selectedColor = '';

  selectColor(color: string): void {
    this.selectedColor = color;
    this.$emit('color-change', { color });
  }
}

Parent template catches the event:

<color-picker @color-change="{onColorChange(e)}"></color-picker>
<p>Selected: {{currentColor}}</p>

Parent class handles the event:

onColorChange(e: CustomEvent): void {
  this.currentColor = e.detail.color;
}

This pattern keeps components decoupled - the child doesn't know who is listening, and the parent reacts declaratively.

Loading Static Component Assets #

When you are not using @microsoft/webui-router, deferred UI can still be loaded from static files. Build the root components as assets:

webui build ./src --out ./dist --plugin=webui \
  --emit-component-assets settings-dialog,mail-thread

Each requested root writes an ESM graph module such as <tag>.webui.js next to protocol.bin. Entry-reachable dependencies remain in the application bundle and protocol. Dependencies used by one requested root stay inline, while dependencies used by the same set of two or more roots are emitted once as chunk-<component>.webui.js and dynamically imported by those roots. Asset-only fragments and component records do not remain in protocol.bin.

Static component assets and <route> cannot be used in the same build. Use @microsoft/webui-router for routed components, or use component assets for non-routed deferred UI.

During development, pass the same flag to webui serve so these roots are validated and served without a separate build step:

webui serve ./src --state ./data/state.json --plugin=webui \
  --emit-component-assets settings-dialog,mail-thread \
  --metafile ./component-assets-meta.json --watch

The dev server parses and validates each root on every build. HTML and theme-token errors in a lazily loaded component fail the build instead of being missed because the component is outside the initial SSR tree. The dev server serves roots and shared chunks from memory and rebuilds them on change. A successful watch build atomically replaces --metafile; a failed build preserves the previous valid graph.

Load the asset before creating or revealing the component:

import { WebUIElement } from '@microsoft/webui-framework';
import { settingsAssets } from './lazy-assets.js';

export class AppShell extends WebUIElement {
  panelSlot!: HTMLDivElement;

  async openSettings(): Promise<void> {
    settingsAssets.preload('settings-dialog');
    this.panelSlot.replaceChildren(await settingsAssets.create('settings-dialog'));
  }
}

// lazy-assets.ts
import { defineComponentAssets } from '@microsoft/webui-framework/component-asset.js';

export const settingsAssets = defineComponentAssets({
  'settings-dialog': {
    asset: '/settings-dialog.webui.js',
    module: () => import('./settings-dialog/settings-dialog.js'),
    data: async () => await (await fetch('/settings-dialog-data.json')).json(),
  },
});

defineComponentAssets() exposes preload(tag) and create(tag). The compiler stores final Link stylesheet hrefs in the protocol. For Shadow builds, the handler publishes that finite manifest as inert JSON in the document head, or at the rendered body start for body-only host protocols. Light builds emit the same hrefs as deduplicated document stylesheets because their CSS is globally scoped. Automatic Shadow intent preloading requires HTML rendered through the WebUI handler or Protocol, which emits #webui-component-assets. A shell that uses the build artifacts without rendering the protocol still mounts safely through the native stylesheet guard, but it cannot start the compiler-owned style preload before loading the root asset. If an authoritative native stylesheet link fails, WebUI reports the error, keeps the native link in place, releases the temporary guard, and completes hydration. The component may be unstyled, but it remains visible and usable. Generated root, shared chunk, and content-hashed stylesheet filenames never belong in authored code. In Shadow builds, preload(tag) starts the component's Link styles, template graph, JavaScript module, and optional data together. Components can then fetch their own data in their class code and expose it through @observable fields when JavaScript needs to read or mutate it. Concurrent roots deduplicate shared chunk and stylesheet work by resolved URL. create(tag) creates the element after template/module work is ready. Use create(tag, { awaitData: true, dataTimeoutMs: 150 }) only when a component must wait briefly for state before mounting. Use a manifest helper when you want the fastest path: it lets the shell start Link CSS, the authored root asset, the JS chunk, and data in parallel. Application code keeps only the stable root asset URL; shared chunk and content-hashed stylesheet names remain compiler-owned. A preload whose intent never mounts the component is removed after three seconds, but the browser may still report its standard unused-preload warning. If the root asset or authored module rejects, the registry evicts that failed generation so the next preload(tag) or create(tag) retries it. Generated bundler integrations can supply asset: () => import('./settings-dialog.webui.js') instead of a URL so chunk loading and public-path rewriting stay bundler-owned without bypassing defineComponentAssets().

Do not put <settings-dialog> in an SSR-reachable <if> block for this pattern. If the server state ever makes that condition true, the component is part of the initial SSR graph instead of being loaded only from the static asset. Always load the normal application entry bundle first; component assets treat all entry-reachable templates as external prerequisites and fail clearly when one is missing.

Styling #

Keep styles in the ordinary paired .css file. For an effective Light component, CSS is authored/global in the owning CSS tree: selectors are not rewritten or marker-scoped. For effective Shadow roots, the browser provides native style scoping.

The :host Selector (Shadow DOM only) #

Style an effective Shadow component's root element with :host:

:host {
  display: block;
  padding: 1rem;
  border: 1px solid #e0e0e0;
}

In effective Light DOM, target the component tag directly instead:

my-card {
  display: block;
  padding: 1rem;
}

Attribute-Based Styling #

In Shadow DOM, style component attributes with :host([attr]):

:host([variant="primary"]) {
  background: #0078d4;
  color: white;
}

:host([disabled]) {
  opacity: 0.5;
  pointer-events: none;
}

The equivalent global Light selector is my-card[variant="primary"] or my-card[disabled]. :host, :host-context, and ::slotted in effective Light CSS fail with unsupported-light-css; use ordinary selectors or opt the component into Shadow DOM.

CSS Ownership Rules #

  • Light DOM uses authored/global selectors and normal inheritance/cascade
  • Light CSS can reach other Light DOM in the same Document or ShadowRoot
  • Use deliberate names, @layer, and custom properties for global composition
  • Shadow DOM provides a native style boundary
  • Shadow-only selectors in Light components fail the build
  • No CSS-in-JS - styles stay in .css files, separate from behavior
  • Use CSS custom properties (--my-color) to allow external theming

SSR + Interactivity Lifecycle #

Understanding the lifecycle helps you write components that work correctly from the first paint through interactive use.

1. Server renders HTML #

The handler renders the component's template using JSON state data. No JavaScript runs. In a Light build, unwrapped content is emitted directly:

<my-counter>
  <button>Count: 0</button>
</my-counter>

The default build and authored Shadow islands emit Declarative Shadow DOM with styles installed inside the shadow root.

2. Browser displays content #

The browser parses the HTML and renders it immediately. The user sees fully styled content - no loading spinner, no blank page, no flash of unstyled content.

3. JavaScript loads and components hydrate #

The framework detects the existing Light or Shadow SSR DOM and upgrades elements in place:

  • Bindings are wired to class properties
  • Event handlers are attached
  • @observable properties become reactive
  • Existing host attributes take precedence over projected @attr state
  • The component is now interactive

4. User interacts #

From this point on, interactions are handled entirely on the client. Changes to @observable properties trigger targeted DOM updates without a server round-trip.

Setting observable state during setup #

The server owns the first paint, and the framework trusts the HTML it produced. Hydration wires bindings to the existing DOM instead of re-rendering it. A value you write before hydration finishes, in an @observable field initializer, the constructor, or before you call super.connectedCallback(), updates the property's backing field but cannot touch the DOM yet, so it is dropped. Your element's state then silently disagrees with what is on screen.

When the framework detects this it logs a development warning naming the properties, so the mismatch is never silent:

[WebUI] Hydration mismatch on <my-counter>: "count" changed at or before
super.connectedCallback() to a value that differs from the server-rendered DOM…

Follow these rules to stay correct:

  • A value that must appear in the first render belongs in the SSR state. Provide it in the JSON state so the server renders it; the client then hydrates against a matching DOM.
  • Assign post-hydration state from hydratedCallback(), where @observable writes flow through live bindings on ordinary, streamed, and client-created components.

On a normal buffered page or client-created mount, super.connectedCallback() hydrates synchronously. A progressive streaming host can connect while its checkpoint or generated parent span is incomplete, so the same call returns while hydration is still deferred. hydratedCallback() is the cross-mode lifecycle: WebUI invokes it synchronously exactly once after the first successful hydration or mount. Its once-latch is set before author code, so reconnecting the element or throwing from the callback does not retry it.

Buffered pages rely on loading authored component code with a parser-inserted, non-async ES module script or a classic defer script. If a classic script blocks parsing, place it after every SSR instance it may upgrade. An opt-in progressive streaming page instead loads an early async module and gates each component until its complete streaming occurrence or generated span commits.

Descendants must not structurally mutate a containing WebUI component's SSR subtree before that component hydrates. Inserting, removing, or reordering nodes can shift compiled element indices before WebUI wires them.

export class MyCounter extends WebUIElement {
  @observable count = 0;

  constructor() {
    super();
    // ✗ Wrong: this runs before hydration, so the write is dropped and warns.
    // this.count = 3;
  }

  protected override hydratedCallback(): void {
    // ✓ Correct: this hook runs after hydration in every mode.
    this.count = 3;
  }
}

If count should already read 3 in the server-rendered HTML, seed it in the SSR state instead of assigning it on the client at all.

Development warning #

The mismatch warning is removed from webui-press production builds. If you bundle the framework yourself, define __WEBUI_DEV__ as false in production:

esbuild app.ts --bundle --minify --define:__WEBUI_DEV__=false

When NOT to Hydrate #

Not every component needs JavaScript. Hydrating a component that has no interactivity adds unnecessary bytes and processing time.

Skip hydration for:

  • Static content pages - about, docs, marketing, legal. The server renders them perfectly.
  • Read-only data displays - lists, tables, cards with no user interaction. Server-rendered HTML is sufficient.
  • Layout components - headers, footers, sidebars with only links. Standard <a> tags work without JS.

Hydrate when a component needs:

  • Event handlers (@click, @keydown, @input)
  • Reactive state updates (@observable properties that change)
  • User input handling (forms, search, filters)
  • Client-side data manipulation (sorting, filtering, pagination)

The goal is minimal JavaScript: hydrate only what the user will interact with, and let the server handle everything else.