WebUI Framework - AI Reference #

BUILD TIME          SERVER RENDER         CLIENT HYDRATION
─────────────       ──────────────        ─────────────────
HTML + CSS + TS →   protocol.bin    →     Web Components
webui build         + JSON state          hydrate as islands
                    → rendered HTML

my-app/
├── src/
│   ├── index.html              ← Entry template
│   ├── index.ts                ← Hydration entry point
│   ├── my-component/
│   │   ├── my-component.html   ← Component template
│   │   ├── my-component.css    ← Component styles (scoped)
│   │   └── my-component.ts     ← Component behavior
│   └── other-widget/
│       ├── other-widget.html
│       ├── other-widget.css
│       └── other-widget.ts
├── data/
│   └── state.json              ← Server state for dev
└── package.json

<!-- my-card.html -->
<h2>{{title}}</h2>
<p>{{description}}</p>

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

<span>{{user.name}}</span>
<p>{{items.length}} items</p>

<if condition="isLoggedIn">
  <p>Welcome back, {{username}}!</p>
</if>

<if condition="!hasItems">
  <p>No items found.</p>
</if>

<if condition="status == 'active'">
  <span class="badge">Active</span>
</if>

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

<!-- Dynamic attribute -->
<a href="{{url}}">{{linkText}}</a>

<!-- Boolean attribute (rendered when truthy, omitted when falsy) -->
<button ?disabled="{{isLoading}}">Submit</button>
<input type="checkbox" ?checked="{{isSelected}}" />

<!-- Boolean attributes accept the same expressions as <if condition="...">.
     Use comparisons against existing state instead of creating mirror observables. -->
<button ?disabled="{{currentIndex == 0}}">Prev</button>
<button ?disabled="{{currentIndex == items.length - 1}}">Next</button>
<option ?selected="{{item.id == selectedId}}">{{item.name}}</option>

<!-- Mixed static + dynamic -->
<img src="/img/{{user.avatar}}" alt="{{user.name}}" />

<!-- Complex/property binding -->
<my-widget :config="{{settings}}"></my-widget>

<button @click="{handleClick()}">Click me</button>
<input @keydown="{onKeydown(e)}" />
<div @mouseenter="{onHover()}" @mouseleave="{onLeave()}">Hover</div>

<input w-ref="searchInput" type="text" />

<route path="/" component="app-shell">
  <route path="" component="home-page" exact />
  <route path="users" component="user-list" exact />
  <route path="users/:id" component="user-detail" exact />
</route>

<!-- Parent component template -->
<nav>...</nav>
<main><outlet /></main>

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

export class MyComponent extends WebUIElement {
  // --- Decorators ---

  // @attr: reflects to/from HTML attribute (kebab-case)
  // String mode (default):
  @attr label = 'Default';

  // Boolean mode (present = true, absent = false):
  @attr({ mode: 'boolean' }) disabled = false;

  // @observable: reactive state, changes trigger DOM updates
  @observable count = 0;
  @observable items: Item[] = [];

  // Derived state: computed in event handlers, not as a getter
  @observable totalPrice = 0;

  private recalcTotal(): void {
    this.totalPrice = this.items.reduce((sum, i) => sum + i.price, 0);
  }

  // --- DOM refs (populated by w-ref="name" in template) ---
  inputEl!: HTMLInputElement;

  // --- Event handlers (referenced by @event in template) ---
  onSubmit(): void {
    const text = this.inputEl.value.trim();
    if (!text) return;
    this.items = [...this.items, { text, price: 0 }];
    this.inputEl.value = '';
  }

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

  // --- Custom events (child-to-parent communication) ---
  onItemDelete(e: CustomEvent<{ id: string }>): void {
    this.items = this.items.filter(i => i.id !== e.detail.id);
  }
}

// Register as custom element
MyComponent.define('my-component');

// Child component
this.$emit('item-selected', { id: this.id, name: this.name });

<!-- Parent template catches it -->
<child-component @item-selected="{onItemSelected(e)}"></child-component>

// Parent handler
onItemSelected(e: CustomEvent): void {
  this.selectedId = e.detail.id;
}

<route path="/" component="app-shell">
  <route path="" component="home-page" exact />
  <route path="users/:id" component="user-detail" exact />
  <!-- Compiled into protocol, but only loaded when needed -->
  <route path="settings" component="settings-dialog" exact />
</route>

// Fetches template + CSS from /_webui/templates — no FOUC
await Router.ensureLoaded('settings-dialog');
this.showSettings = true;

// Batch multiple in one request
await Router.ensureLoaded('modal-a', 'modal-b', 'drawer-c');

Router.start({
  templateEndpoint: '/api/templates', // default: '/_webui/templates'
  loaders: { ... },
});

/* my-component.css */
:host {
  display: block;
  padding: 1rem;
}

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

:host([variant="primary"]) {
  background: var(--colorBrandBackground);
}

/* Internal elements */
.header { font-weight: bold; }
.content { padding: 0.5rem; }

<!DOCTYPE html>
<html lang="en" dir="{{textdirection}}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
</head>
<body>
  <app-shell></app-shell>
  <script type="module" src="/index.js"></script>
</body>
</html>

// index.ts
import { WebUIElement } from '@microsoft/webui-framework';

// Import components to register them as custom elements.
// Registration triggers hydration automatically.
import './app-shell/app-shell.js';
import './user-card/user-card.js';

// Optional: listen for hydration completion
window.addEventListener('webui:hydration-complete', () => {
  const total = performance.getEntriesByName('webui:hydrate:total', 'measure')[0];
  console.log(`Hydration: ${total?.duration.toFixed(1)}ms`);
});

// index.ts
import { WebUIElement } from '@microsoft/webui-framework';
import { Router } from '@microsoft/webui-router';
import './app-shell/app-shell.js';

// Start router after components are registered
Router.start({
  loaders: {
    'home-page': () => import('./pages/home-page.js'),
    'user-list': () => import('./pages/user-list.js'),
    'user-detail': () => import('./pages/user-detail.js'),
  },
});

.content-area { view-transition-name: content; }

::view-transition-old(content) { animation: fade-out 100ms ease-out; }
::view-transition-new(content) { animation: fade-in 150ms ease-in; }

webui build ./src --out ./dist --plugin=webui

webui serve ./src --state ./data/state.json --plugin=webui --watch

webui inspect ./dist/protocol.bin
webui inspect ./dist/protocol.bin | jq '.fragments | keys'

{
  "name": "@scope/my-button",
  "customElements": "./custom-elements.json",
  "exports": {
    "./template-webui.html": "./dist/template-webui.html",
    "./styles.css": "./dist/styles.css"
  }
}

# Single scoped package
webui build ./src --out ./dist --components @reactive-ui/button

# All packages under a scope
webui build ./src --out ./dist --components @reactive-ui

# Local shared library
webui build ./src --out ./dist --components ./shared/components

# Multiple sources
webui build ./src --out ./dist \
  --components @reactive-ui \
  --components ./shared/components

{
  "themes": {
    "light": {
      "surface-page": "#ffffff",
      "text-primary": "#111827"
    },
    "dark": {
      "surface-page": "#171717",
      "text-primary": "#fafafa"
    }
  }
}

{
  "surface-page": "#ffffff",
  "text-primary": "#111827"
}

<style>
  :root {
    <!--{{{tokens.light}}}-->
  }
</style>

:root {
  --surface-page: #ffffff;
  --text-primary: #111827;
}

{
  "title": "My App",
  "user": { "name": "Alice", "role": "admin" },
  "items": [
    { "id": "1", "label": "First", "done": false },
    { "id": "2", "label": "Second", "done": true }
  ],
  "isAdmin": true,
  "showBanner": false
}

<button @click="{togglePanel()}">Toggle</button>
<if condition="isPanelOpen">
  <div class="panel">Panel content</div>
</if>

@observable isPanelOpen = false;
togglePanel(): void { this.isPanelOpen = !this.isPanelOpen; }

<input w-ref="input" @keydown="{onKey(e)}" />
<for each="item in items">
  <div>
    {{item.text}}
    <button @click="{remove(item.id)}">×</button>
  </div>
</for>

<for each="item in items">
  <list-item id="{{item.id}}" text="{{item.text}}"
    @remove-item="{onRemove(e)}">
  </list-item>
</for>

<button ?data-active="{{isActive}}" @click="{toggle()}">
  {{label}}
</button>

button[data-active] { background: blue; color: white; }
button:not([data-active]) { background: transparent; }

<!-- index.html — settings-dialog is in the protocol but not navigated to -->
<route path="/" component="app-shell">
  <route path="" component="home-page" exact />
  <route path="settings" component="settings-dialog" exact />
</route>

// Shell component — load template + CSS on demand
async onOpenSettings(): Promise<void> {
  await Router.ensureLoaded('settings-dialog');
  await import('./settings-dialog/settings-dialog.js');
  this.showSettings = true;
}

<!-- Shell template — create the element dynamically -->
<if condition="showSettings">
  <settings-dialog @close="{onCloseSettings()}"></settings-dialog>
</if>

<!-- DO: derive in the template -->
<if condition="items.length">
  <span>{{items.length}} items</span>
</if>

<button ?disabled="{{currentIndex == 0}}">Prev</button>
<button ?disabled="{{currentIndex == totalItems}}">Next</button>

<for each="app in apps">
  <option ?selected="{{app.slug == currentApp.slug}}">{{app.name}}</option>
</for>

<!-- DON'T: shadow observables that mirror a comparison -->
<!-- @observable hasItems = false;     // mirrors items.length > 0 -->
<!-- @observable prevDisabled = true;  // mirrors currentIndex == 0 -->
<!-- @observable nextDisabled = false; // mirrors currentIndex == totalItems -->

<!-- DON'T: per-item flags in JSON state that mirror a comparison -->
<!-- { "apps": [{ "slug": "...", "isCurrent": true }, ...] }
     Just compare against the selected slug/id in the template. -->

// GET /inbox -> only inbox data
{ "threads": [...], "selectedFolder": "inbox" }

// GET /settings -> only settings data
{ "theme": "dark", "language": "en" }

{
  "scripts": {
    "build": "webui build ./src --out ./dist --plugin=webui",
    "dev": "webui serve ./src --state ./data/state.json --plugin=webui --watch"
  },
  "dependencies": {
    "@microsoft/webui": "latest",
    "@microsoft/webui-framework": "latest"
  }
}

let protocol = WebUIProtocol::from_protobuf(&fs::read("dist/protocol.bin")?)?;
let state = json!({ "title": "Home", "items": items_vec });
let mut handler = WebUIHandler::new();
handler.handle(&protocol, &state, &options, &mut writer)?;

import { render } from '@microsoft/webui';
const protocol = readFileSync('./dist/protocol.bin');
const html = render(protocol, JSON.stringify(state), 'index.html', req.url);

ptr = lib.webui_render(html_bytes, json_bytes)
result = ctypes.cast(ptr, c_char_p).value.decode("utf-8")
lib.webui_free(ptr)

ptr := C.webui_render(cHTML, cJSON)
defer C.webui_free(ptr)
result := C.GoString(ptr)

IntPtr ptr = webui_render(html, dataJson);
string result = Marshal.PtrToStringUTF8(ptr);
webui_free(ptr);

let result = route_handler::render_component_templates(&protocol, &tags, &inv);

// Node native addon
const result = renderComponentTemplates(protocolBuf, JSON.stringify(tags), invHex);

// @microsoft/webui npm package
import { renderComponentTemplates } from '@microsoft/webui';
const result = renderComponentTemplates(protocolBuf, ['settings-dialog'], invHex);