No results found.

REST Verbs

xh-get attribute #

Issue a GET request to the specified URL. The JSON response is rendered via a template and swapped into the DOM.

Syntax

<element xh-get="/api/endpoint">

Example

<button xh-get="/api/users"
        xh-template="/templates/user-list.html"
        xh-target="#results">
  Load Users
</button>
<div id="results"></div>

xh-post attribute #

Issue a POST request. Form fields, xh-vals, and xh-model values are serialized as JSON in the request body. Content-Type defaults to application/json.

Example

<form xh-post="/api/users" xh-template="/templates/success.html">
  <input name="name" type="text">
  <button type="submit">Create</button>
</form>

xh-put attribute #

Issue a PUT request. Behaves identically to xh-post but uses the PUT HTTP method.

Example

<button xh-put="/api/users/{{id}}"
        xh-vals='{"name":"Alice"}'>
  Update
</button>

xh-delete attribute #

Issue a DELETE request to the specified URL.

Example

<button xh-delete="/api/users/{{id}}" xh-swap="delete">
  Remove
</button>

xh-patch attribute #

Issue a PATCH request. Sends a JSON body like xh-post and xh-put.

Example

<button xh-patch="/api/users/{{id}}"
        xh-vals='{"role":"admin"}'>
  Promote
</button>

Templates

xh-template attribute #

URL of an external HTML template file to render with the JSON response data. If omitted, the library looks for an inline <template> child, or falls back to self-binding (applying bindings directly to the element).

Syntax

<element xh-get="/api/data" xh-template="/templates/view.html">

Inline template alternative

<div xh-get="/api/users">
  <template>
    <span xh-text="name"></span>
  </template>
</div>

Templates are cached after first fetch. Use xhtmlx.clearTemplateCache() to clear. Templates can contain nested xh-* attributes for composition.

xh-name attribute #

Defines a named inline template. Place <template xh-name="/path"> anywhere in the document; its content is cached and can be referenced by other elements via xh-template="/path" without a network request.

Example

<template xh-name="/templates/user-card.html">
  <div class="card"><h3 xh-text="name"></h3></div>
</template>

<div xh-get="/api/user/1" xh-trigger="load"
     xh-template="/templates/user-card.html"></div>

Named templates are scanned on DOMContentLoaded. Call xhtmlx.scanNamedTemplates() after dynamically adding new ones.

Data Binding

xh-text attribute #

Set the element's textContent to the value of the given data field. Supports dot notation and the pipe transform syntax.

Syntax

<span xh-text="field.path"></span>
<span xh-text="price | currency"></span>

Reactive: when backed by a MutableDataContext, updates automatically when the field value changes.

xh-html attribute #

Set the element's innerHTML to the value of the given data field. Use with caution as it can introduce XSS vulnerabilities. Disabled in CSP-safe mode (falls back to textContent).

Example

<div xh-html="user.bio_html"></div>

xh-attr-* attribute #

Set any HTML attribute from a data field. The part after xh-attr- becomes the target attribute name.

Example

<img xh-attr-src="user.avatar" xh-attr-alt="user.name">
<a xh-attr-href="user.profile_url" xh-text="user.name"></a>

Reactive when backed by a MutableDataContext.

Iteration & Conditionals

xh-each attribute #

Repeat the element for each item in an array field. Each clone receives its own data context scoped to the array item. Use $index for the zero-based iteration index, $parent to access the parent context, and $root for the root context.

Example

<ul>
  <li xh-each="items">
    <span xh-text="$index"></span>. <span xh-text="name"></span>
  </li>
</ul>

Special variable	Description
`$index`	Current iteration index (0-based)
`$parent`	Parent data context
`$root`	Root (topmost) data context

For arrays larger than config.batchThreshold (default 100), rendering may use batching for performance.

xh-if attribute #

Conditionally render the element. If the referenced data field is falsy, the element is removed from the DOM entirely.

Example

<span xh-if="is_admin" class="badge">Admin</span>

xh-unless attribute #

Inverse of xh-if. Removes the element if the data field is truthy.

Example

<span xh-unless="verified" class="warning">Unverified</span>

xh-show attribute #

Toggle element visibility via display style. Sets display:none when falsy, clears it when truthy. Unlike xh-if, the element remains in the DOM. Reactivity-aware with MutableDataContext.

Example

<div xh-show="has_details">Details here</div>

xh-hide attribute #

Inverse of xh-show. Hides the element when the data field is truthy. Reactivity-aware.

Example

<div xh-hide="is_loading">Content ready</div>

Dynamic CSS Classes

xh-class-* attribute #

Toggle a CSS class based on a data field. The part after xh-class- is the class name; the attribute value is the data field to evaluate. Reactivity-aware.

Syntax

<element xh-class-{className}="dataField">

Example

<div xh-class-active="is_active"
     xh-class-highlight="is_featured">
  Content
</div>

Model & Reactivity

xh-model attribute #

Two-way data binding for form inputs. Pre-fills input values from the data context. When the user edits the input, the data context is updated (if mutable). Values from xh-model inputs are automatically included in request bodies alongside form fields and xh-vals.

Element type	Behavior
Text input / textarea	Binds to `.value`, listens on `input`
Checkbox	Binds to `.checked` (boolean), listens on `change`
Radio button	Checks if `.value === data`, listens on `change`
Select	Sets matching option, listens on `change`

Example

<div xh-get="/api/user/1" xh-trigger="load">
  <template>
    <input type="text" xh-model="name">
    <select xh-model="role">
      <option value="user">User</option>
      <option value="admin">Admin</option>
    </select>
    <input type="checkbox" xh-model="active">
    <button xh-put="/api/user/1">Save</button>
  </template>
</div>

Triggers

xh-trigger attribute #

Specifies which event fires the REST request. Multiple triggers can be comma-separated. If omitted, defaults are used: click for buttons/links, submit for forms, change for inputs/selects/textareas.

Syntax

xh-trigger="event [modifiers]"
xh-trigger="event1 [mods], event2 [mods]"

Trigger / Modifier	Description
`load`	Fire immediately when the element is processed
`revealed`	Fire when scrolled into the viewport (IntersectionObserver)
`every Ns` / `every Nms`	Polling: repeat at the given interval
`once`	Fire only once, then remove the listener
`changed`	Only fire if the source value has changed
`delay:Nms`	Debounce: wait N ms after the last event before firing
`throttle:Nms`	Throttle: fire at most once every N ms
`from:selector`	Listen on a different element (specified by CSS selector)

Examples

<div xh-get="/api/data" xh-trigger="load">Auto-load</div>

<input xh-get="/api/search" xh-trigger="keyup changed delay:300ms">

<div xh-get="/api/feed" xh-trigger="every 5s">Polling</div>

<div xh-get="/api/more" xh-trigger="revealed">Lazy load</div>

<button xh-get="/api/data" xh-trigger="click once">Load once</button>

Targeting & Swap

xh-target attribute #

CSS selector specifying where the rendered template result is placed. If omitted, the triggering element itself is used as the target. The target element automatically receives aria-live for accessibility.

Example

<button xh-get="/api/users" xh-target="#user-list">Load</button>
<div id="user-list"></div>

xh-swap attribute #

Controls how rendered content is inserted into the target element. Defaults to innerHTML (configurable via config.defaultSwapMode).

Mode	Behavior
`innerHTML`	Replace the target's children (default)
`outerHTML`	Replace the target element itself
`beforeend`	Append inside the target
`afterbegin`	Prepend inside the target
`beforebegin`	Insert before the target
`afterend`	Insert after the target
`delete`	Remove the target from the DOM
`none`	Fire-and-forget; no DOM swap

Example

<button xh-get="/api/messages"
        xh-target="#chat"
        xh-swap="beforeend">
  Load More
</button>

After each swap, settle classes (xh-added then xh-settled) are applied for CSS transition support.

Request Data

xh-vals attribute #

JSON string of additional values to include in the request body. Merged with form fields and xh-model values. Supports {{field}} interpolation.

Example

<button xh-post="/api/users"
        xh-vals='{"name":"Alice","role":"admin"}'>
  Create
</button>

xh-headers attribute #

JSON string of custom HTTP headers to send with the request. Supports {{field}} interpolation.

Example

<button xh-get="/api/secure"
        xh-headers='{"X-Custom":"value","Authorization":"Bearer {{token}}"}'>
  Fetch
</button>

Declarative Event Handlers (xh-on-*)

xh-on-* attribute #

Attach client-side event handlers declaratively. The part after xh-on- is the DOM event name. The attribute value is an action string.

Syntax

<element xh-on-{event}="action:argument">

Action	Description
`toggleClass:name`	Toggle a CSS class on the element
`addClass:name`	Add a CSS class
`removeClass:name`	Remove a CSS class
`remove`	Remove the element from the DOM
`toggle:selector`	Toggle visibility of another element
`dispatch:eventName`	Dispatch a custom DOM event (bubbles)

Examples

<button xh-on-click="toggleClass:active">Toggle</button>
<button xh-on-click="toggle:#details">Show/Hide Details</button>
<button xh-on-click="dispatch:myEvent">Fire Event</button>
<button xh-on-dblclick="remove">Double-click to remove</button>

Indicators

xh-indicator attribute #

CSS selector of a loading indicator element. While the request is in-flight, the xh-request class is added to the indicator. Default CSS is injected to show/hide elements with the xh-indicator class.

Example

<button xh-get="/api/data" xh-indicator="#spinner">Load</button>
<span id="spinner" class="xh-indicator">Loading...</span>

Default CSS: .xh-indicator { opacity: 0; } and .xh-request .xh-indicator { opacity: 1; }

xh-disabled-class attribute #

CSS class to add to the triggering element while a request is in-flight (request deduplication). Also sets aria-disabled="true". Subsequent triggers are ignored until the request completes.

Example

<button xh-post="/api/submit"
        xh-disabled-class="btn-loading">
  Submit
</button>

Error Handling

xh-error-template attribute #

URL of a template to render when the request returns an error HTTP status. Supports status-specific variants.

Syntax

xh-error-template="/templates/error.html"
xh-error-template-404="/templates/not-found.html"
xh-error-template-4xx="/templates/client-error.html"
xh-error-template-5xx="/templates/server-error.html"

Resolution order: (1) exact status code on element, (2) status class (4xx/5xx) on element, (3) generic on element, (4) nearest xh-error-boundary ancestor, (5) config.defaultErrorTemplate, (6) no template (adds xh-error CSS class).

Error data context contains status, statusText, and body fields.

Error template example

<div class="error">
  <h3>Error <span xh-text="status"></span></h3>
  <p xh-text="statusText"></p>
</div>

xh-error-target attribute #

CSS selector specifying where to render the error template. If omitted, falls back to boundary target, config.defaultErrorTarget, xh-target, or the element itself. The error container is marked with role="alert" for screen readers.

Example

<div xh-get="/api/data"
     xh-error-template="/templates/error.html"
     xh-error-target="#error-area"></div>
<div id="error-area"></div>

xh-error-boundary attribute #

Marks an ancestor element as an error boundary. Child widgets without their own error templates bubble errors up to the nearest boundary. Boundaries nest -- the closest ancestor wins. Supports status-specific templates like the element-level attributes.

Example

<div xh-error-boundary
     xh-error-template="/templates/section-error.html"
     xh-error-target="#section-errors">
  <div id="section-errors"></div>
  <div xh-get="/api/widget" xh-trigger="load">
    <template><span xh-text="data"></span></template>
  </div>
</div>

History

xh-push-url attribute #

Push a new browser history entry after a successful request. Set to "true" to use the request URL, or provide a custom URL (supports {{field}} interpolation). Back/forward navigation re-fetches data and re-renders the template.

Example

<button xh-get="/api/users/{{id}}"
        xh-push-url="/users/{{id}}"
        xh-target="#content">
  View User
</button>

xh-replace-url attribute #

Replace the current browser history entry (instead of pushing a new one) after a successful request. Same value semantics as xh-push-url.

Example

<button xh-get="/api/search?q=test"
        xh-replace-url="/search?q=test"
        xh-target="#results">
  Search
</button>

WebSocket

xh-ws attribute #

Open a WebSocket connection to the given URL. Each incoming JSON message is rendered via the element's template and swapped into the target. Auto-reconnects after 3 seconds on unexpected disconnection.

Example

<div xh-ws="wss://example.com/feed"
     xh-swap="beforeend"
     xh-target="#messages">
  <template>
    <div class="msg">
      <strong xh-text="user"></strong>: <span xh-text="text"></span>
    </div>
  </template>
</div>
<div id="messages"></div>

xh-ws-send attribute #

Send data over an existing WebSocket connection. The value is a CSS selector pointing to the element with the xh-ws connection. Form fields and xh-vals are serialized as JSON.

Example

<div id="chat-ws" xh-ws="wss://example.com/chat">...</div>
<form xh-ws-send="#chat-ws">
  <input name="text" type="text">
  <button type="submit">Send</button>
</form>

Boost

xh-boost attribute #

Enhance all <a> links and <form> elements within the container to use AJAX instead of full-page navigation. Boosted links automatically push browser history. Links with target="_blank", mailto:, or hash-only hrefs are excluded.

Example

<nav xh-boost xh-boost-target="#main" xh-boost-template="/templates/page.html">
  <a href="/about">About</a>
  <a href="/contact">Contact</a>
</nav>
<div id="main"></div>

xh-boost-target attribute #

CSS selector for where boosted content is swapped. Placed on the xh-boost container. Defaults to #xh-boost-content.

xh-boost-template attribute #

Template URL used to render JSON responses from boosted links/forms. Placed on the xh-boost container.

Caching & Retry

xh-cache attribute #

Cache GET responses. Value is the TTL in seconds, or "forever" to cache until page reload or manual clear. Only applies to GET requests.

Examples

<div xh-get="/api/config" xh-trigger="load" xh-cache="60">...</div>
<div xh-get="/api/static" xh-trigger="load" xh-cache="forever">...</div>

xh-retry attribute #

Maximum number of retry attempts for failed requests (5xx errors and network failures). Uses exponential backoff.

Example

<div xh-get="/api/flaky"
     xh-retry="3"
     xh-retry-delay="1000">...</div>

Delays double each attempt: 1s, 2s, 4s. Emits xh:retry on each attempt.

xh-retry-delay attribute #

Base delay in milliseconds for retry backoff. Defaults to 1000. Doubled on each subsequent attempt.

Validation

xh-validate attribute #

Enable validation on an input element. Currently supports the required rule. Validation runs automatically before sending a request; if it fails, the request is blocked and xh:validationError is emitted.

Example

<input name="username" xh-validate="required"
       xh-validate-minlength="3"
       xh-validate-maxlength="20"
       xh-validate-message="Username must be 3-20 characters"
       xh-validate-target="#username-error">
<span id="username-error"></span>

xh-validate-pattern attribute #

Regex pattern the input value must match. Tested via new RegExp(pattern).test(value).

Example

<input name="email" xh-validate="required"
       xh-validate-pattern="^[^@]+@[^@]+$">

xh-validate-min attribute #

Minimum numeric value. The input's value is compared as a number.

xh-validate-max attribute #

Maximum numeric value.

Example

<input name="age" type="number" xh-validate="required"
       xh-validate-min="18" xh-validate-max="120">

xh-validate-minlength attribute #

Minimum string length for the input value.

xh-validate-maxlength attribute #

Maximum string length for the input value.

xh-validate-message attribute #

Custom error message displayed when validation fails. If omitted, a default message is generated from the field name and rule.

xh-validate-class attribute #

CSS class applied to invalid fields. Defaults to xh-invalid.

xh-validate-target attribute #

CSS selector of an element where the validation error message is displayed (via textContent).

i18n (Internationalization)

xh-i18n attribute #

Set the element's textContent from an i18n translation key. The key is looked up in the current locale dictionary (loaded via xhtmlx.i18n.load()). Re-renders automatically on locale change.

Example

<h1 xh-i18n="greeting" xh-i18n-vars='{"name":"Alice"}'></h1>
<button xh-i18n="submit"></button>

xh-i18n-* attribute #

Translate an HTML attribute. The part after xh-i18n- is the target attribute name (except vars). The value is the translation key.

Example

<input xh-i18n-placeholder="search_placeholder">
<img xh-i18n-alt="logo_alt" src="logo.png">

xh-i18n-vars attribute #

JSON string of variables for interpolation in translation strings. Variables are substituted using {name} placeholders in the translation value.

Example

<!-- Translation: "greeting": "Hello, {name}!" -->
<span xh-i18n="greeting" xh-i18n-vars='{"name":"Bob"}'></span>
<!-- Output: Hello, Bob! -->

Routing

xh-router attribute #

Marks a container as a client-side router. Contains xh-route links. Scanned on DOMContentLoaded. The router handles browser back/forward via popstate and resolves the current URL on init.

xh-route attribute #

Defines a route path within an xh-router container. Supports path parameters with :param syntax. The active route link receives the xh-route-active CSS class. Combine with xh-get and xh-template for data-driven routes.

Example

<nav xh-router xh-router-outlet="#view" xh-router-404="/templates/404.html">
  <a xh-route="/" xh-template="/templates/home.html">Home</a>
  <a xh-route="/users" xh-get="/api/users"
     xh-template="/templates/users.html">Users</a>
  <a xh-route="/users/:id" xh-get="/api/users/{{id}}"
     xh-template="/templates/user.html">User</a>
</nav>
<div id="view"></div>

xh-router-outlet attribute #

CSS selector of the element where routed content is rendered. Placed on the xh-router container. Defaults to #router-outlet.

xh-router-404 attribute #

Template URL rendered when no route matches the current path. Placed on the xh-router container. The data context contains { path: "..." }.

xh-focus attribute #

Manage focus after a content swap. Set to a CSS selector to focus a specific element, or "auto" to focus the first focusable element (a, button, input, select, textarea, [tabindex]) in the swapped content.

Examples

<button xh-get="/api/form" xh-target="#panel"
        xh-focus="#panel input:first-child">Open Form</button>

<button xh-get="/api/data" xh-target="#content"
        xh-focus="auto">Load</button>

xh-aria-live attribute #

Override the default aria-live value set on target elements. By default, xh-target elements receive aria-live="polite". Set this to "assertive" for urgent updates.

Example

<button xh-get="/api/alerts" xh-target="#alerts"
        xh-aria-live="assertive">Check</button>

Additional automatic accessibility features: aria-busy="true" on targets during requests, role="alert" on error containers, aria-disabled="true" during deduplication.

JavaScript API

xhtmlx.process() method #

Manually process a DOM node and its descendants, scanning for xh-* attributes and attaching triggers. Called automatically on DOMContentLoaded and by the MutationObserver. Call manually after programmatically inserting HTML with xh-* attributes.

Syntax

xhtmlx.process(root, ctx)

Parameter	Type	Description
`root`	Element	DOM element to process. Defaults to `document.body`.
`ctx`	DataContext	Optional data context. Defaults to an empty context.

Example

var el = document.getElementById("dynamic-section");
xhtmlx.process(el);

xhtmlx.createContext() method #

Create a DataContext for programmatic use. Data contexts hold JSON data and can be chained via parent references.

Syntax

xhtmlx.createContext(data, parent, index)

Parameter	Type	Description
`data`	Object	JSON data for this context level
`parent`	DataContext	Optional parent context
`index`	number	Optional iteration index (for `$index`)

Example

var ctx = xhtmlx.createContext({ name: "Alice", role: "admin" });
xhtmlx.process(document.getElementById("widget"), ctx);

xhtmlx.switchVersion() method #

Hot-swap UI templates and API endpoints without a full page reload. Clears template and response caches, then re-renders all active widgets. Emits xh:versionChanged.

Syntax

xhtmlx.switchVersion(version, opts)

Parameter	Type	Description
`version`	string	Version identifier (e.g. "v2", git SHA)
`opts.templatePrefix`	string	Template URL prefix. Defaults to `"/ui/{version}"`
`opts.apiPrefix`	string	API URL prefix. Defaults to unchanged
`opts.reload`	boolean	Re-render widgets. Defaults to `true`

Example

xhtmlx.switchVersion("v2");
xhtmlx.switchVersion("abc123", {
  templatePrefix: "/static/abc123",
  apiPrefix: "/api/v2"
});

xhtmlx.reload() method #

Re-fetch data and re-render all active widgets, or only those using a specific template. Useful after cache invalidation or version switches.

Syntax

xhtmlx.reload(templateUrl)

Parameter	Type	Description
`templateUrl`	string	Optional. If provided, only reload widgets using this template.

Example

xhtmlx.reload(); // all widgets
xhtmlx.reload("/templates/user-list.html"); // specific template only

xhtmlx.directive() method #

Register a custom directive that is processed during applyBindings. The handler is called for each element that has the matching attribute.

Syntax

xhtmlx.directive(name, handler)

Parameter	Type	Description
`name`	string	Attribute name (e.g. "xh-tooltip")
`handler`	function	Called with `(element, attributeValue, dataContext)`

Example

xhtmlx.directive("xh-tooltip", function(el, value, ctx) {
  el.title = ctx.resolve(value);
});

xhtmlx.hook() method #

Register a global hook that runs before or after certain lifecycle events. Return false from a beforeRequest hook to cancel the request.

Syntax

xhtmlx.hook(event, handler)

Parameter	Type	Description
`event`	string	Hook event name (e.g. "beforeRequest")
`handler`	function	Called with the event detail object. Return `false` to cancel.

Example

xhtmlx.hook("beforeRequest", function(detail) {
  detail.headers["Authorization"] = "Bearer " + getToken();
});

xhtmlx.transform() method #

Register a named value transform for the pipe syntax in xh-text and other binding expressions. Transforms can be chained: "value | trim | uppercase".

Syntax

xhtmlx.transform(name, fn)

Example

xhtmlx.transform("currency", function(value) {
  return "$" + Number(value).toFixed(2);
});
// Usage: <span xh-text="price | currency"></span>

xhtmlx.i18n method #

The internationalization module. Load locale dictionaries, switch locales at runtime, and translate strings programmatically.

Property / Method	Description
`i18n.load(locale, translations)`	Load a translation dictionary for a locale
`i18n.locale`	Get/set the current locale. Setting re-renders all `xh-i18n` elements and emits `xh:localeChanged`
`i18n.t(key, vars)`	Translate a key with optional variable interpolation. Falls back to `"en"` locale, then to the key itself

Example

xhtmlx.i18n.load("en", { "greeting": "Hello, {name}!" });
xhtmlx.i18n.load("es", { "greeting": "Hola, {name}!" });
xhtmlx.i18n.locale = "es";
console.log(xhtmlx.i18n.t("greeting", { name: "Bob" })); // "Hola, Bob!"

xhtmlx.router method #

The client-side SPA router module. Navigate programmatically and access route state.

Property / Method	Description
`router.navigate(path)`	Navigate to a path, pushing browser history and resolving the route

Example

xhtmlx.router.navigate("/users/42");

xhtmlx.config config #

Global configuration object. See the Configuration section below for all options.

Example

xhtmlx.config.debug = true;
xhtmlx.config.defaultSwapMode = "innerHTML";

xhtmlx.scanNamedTemplates() method #

Scan the document for <template xh-name="..."> elements and populate the template cache. Called automatically on DOMContentLoaded. Call manually after dynamically adding named templates.

Syntax

xhtmlx.scanNamedTemplates()

xhtmlx.clearTemplateCache() method #

Clear the in-memory template cache. Subsequent template references will re-fetch from the server.

Syntax

xhtmlx.clearTemplateCache()

xhtmlx.clearResponseCache() method #

Clear the in-memory response cache (used by xh-cache).

Syntax

xhtmlx.clearResponseCache()

Events

xh:beforeRequest event #

Fired on the triggering element before a fetch request is sent. Cancelable -- call event.preventDefault() to abort the request.

detail property	Description
`url`	The request URL
`method`	HTTP method (GET, POST, etc.)
`headers`	Request headers object

Example

document.body.addEventListener("xh:beforeRequest", function(e) {
  if (!isAuthenticated()) e.preventDefault();
});

xh:afterRequest event #

Fired after a fetch completes (before template rendering). Not cancelable.

detail property	Description
`url`	The request URL
`status`	HTTP status code

xh:beforeSwap event #

Fired before the rendered content is swapped into the DOM. Cancelable.

detail property	Description
`target`	The swap target element
`fragment`	The DocumentFragment to be inserted
`swapMode`	The swap mode string
`isError`	`true` if this is an error template swap

xh:afterSwap event #

Fired after content has been swapped into the DOM. Not cancelable.

detail property	Description
`target`	The swap target element
`isError`	`true` if this was an error template swap

xh:responseError event #

Fired when the server returns an error HTTP status. Not cancelable.

detail property	Description
`status`	HTTP status code
`statusText`	HTTP status text
`body`	Parsed response body (JSON object or string)

Example

document.body.addEventListener("xh:responseError", function(e) {
  console.log("Error", e.detail.status, e.detail.body);
});

xh:retry event #

Fired before each retry attempt. Not cancelable.

detail property	Description
`attempt`	Current attempt number (1-based)
`maxRetries`	Maximum retry count
`status`	HTTP status (if available)
`error`	Error message (if network error)

xh:validationError event #

Fired when validation fails. Not cancelable.

detail property	Description
`errors`	Array of `{ field, message, element }` objects

xh:wsOpen event #

Fired when a WebSocket connection is established.

detail property	Description
`url`	The WebSocket URL

xh:wsClose event #

Fired when a WebSocket connection closes. Auto-reconnects after 3 seconds if the close code is not 1000 (normal closure).

detail property	Description
`code`	WebSocket close code
`reason`	Close reason string

xh:wsError event #

Fired on WebSocket error.

detail property	Description
`url`	The WebSocket URL

xh:versionChanged event #

Fired on document.body after switchVersion() completes.

detail property	Description
`version`	New version string
`templatePrefix`	New template prefix
`apiPrefix`	New API prefix

xh:localeChanged event #

Fired on document.body when the i18n locale is changed.

detail property	Description
`locale`	New locale string

xh:routeChanged event #

Fired on the router outlet element after a route is resolved.

detail property	Description
`path`	The matched path
`params`	Object of extracted path parameters

xh:routeNotFound event #

Fired on document.body when no route matches the current path.

detail property	Description
`path`	The unmatched path

Configuration

debug config #

Enable debug logging to the console. Logs unresolved interpolations, missing targets, request deduplication skips, and more.

Default

xhtmlx.config.debug = false;

defaultSwapMode config #

Default swap mode when xh-swap is not specified on an element.

Default

xhtmlx.config.defaultSwapMode = "innerHTML";

batchThreshold config #

Arrays above this size in xh-each may use batched rendering for performance.

Default

xhtmlx.config.batchThreshold = 100;

templatePrefix config #

String prepended to all xh-template URLs. Used by switchVersion() to version template paths.

Default

xhtmlx.config.templatePrefix = "";

apiPrefix config #

String prepended to all REST verb URLs (unless the URL contains ://). Used for API versioning.

Default

xhtmlx.config.apiPrefix = "";

defaultErrorTemplate config #

Global fallback error template URL. Used when an element has no xh-error-template and no ancestor xh-error-boundary.

Default

xhtmlx.config.defaultErrorTemplate = null;

defaultErrorTarget config #

Global fallback CSS selector for where to render error templates.

Default

xhtmlx.config.defaultErrorTarget = null;

cspSafe config #

When true, avoids innerHTML for CSP compliance. Uses DOMParser and adopted stylesheets instead. xh-html falls back to textContent.

Default

xhtmlx.config.cspSafe = false;

uiVersion config #

Current UI version identifier. Set automatically by switchVersion(). Can be any string.

Default

xhtmlx.config.uiVersion = null;