# pardnchiu/QuickUI

> QuickUI is a zero-dependency virtual DOM frontend framework in vanilla JavaScript with no build step, by 邱敬幃 Pardn Chiu (pardnchiu).

Every documentation page in navigation order; each section starts with its source URL.

---

Source: https://quickui.pardn.io/index.md

> [!NOTE]
> This README was generated by [SKILL](https://github.com/agenvoy/skill-readme-generate), get the ZH version from [here](https://github.com/pardnchiu/QuickUI/blob/main/doc/README.zh.md).

***

<p align="center">
<strong>A ZERO-DEPENDENCY VIRTUAL DOM FRAMEWORK THAT RUNS WITHOUT A BUILD STEP</strong>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@pardnchiu/quickui"><img src="https://img.shields.io/npm/v/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="npm"></a>
<a href="https://www.jsdelivr.com/package/npm/@pardnchiu/quickui"><img src="https://img.shields.io/jsdelivr/npm/hm/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="Downloads"></a>
<a href="https://www.npmjs.com/package/@pardnchiu/quickui"><img src="https://img.shields.io/npm/l/@pardnchiu/quickui?include_prereleases&style=for-the-badge" alt="License"></a>
</p>

***

> A vanilla JavaScript frontend framework with virtual DOM diffing, declarative HTML templates, and runtime i18n

## Table of Contents

- [Features](#features)
- [Architecture](#architecture)
- [License](#license)
- [Author](#author)

## Features

> `npm i @pardnchiu/quickui` · [Documentation](https://github.com/pardnchiu/QuickUI/blob/main/doc/doc.md)

- **Zero dependencies, no build step** — Native browser APIs power the virtual DOM diff/patch engine, so a single script tag brings it to any existing page.
- **Declarative HTML templates** — Interpolation, loops, conditionals, two-way binding, and event binding live directly in HTML attributes, so the template is the page itself.
- **Batched Proxy reactivity** — Deep data mutations trigger a 300ms debounced update that applies only the required DOM patches on the next animation frame.
- **Runtime i18n switching** — Locales accept either inline objects or JSON file URLs, and a single language switch re-renders both text and attributes.
- **Built-in lazy images and inline SVG** — IntersectionObserver defers image loading behind a placeholder animation and inlines external SVG files as stylable nodes once they enter the viewport.

## Architecture

> [Full Architecture](https://github.com/pardnchiu/QuickUI/blob/main/doc/architecture.md)

```mermaid
graph TB
    A[HTML Template / render Function] --> B[vDOM Build]
    D[Proxy Reactive Data] -->|Change, 300ms Debounce| B
    E[i18n Locale Data] --> B
    B --> C[Diff to Patches]
    C -->|requestAnimationFrame| F[Real DOM]
    G[Lifecycle Hooks] -.-> B
    F --> H[Lazyload / SVG Listeners]
```

## License

This project is licensed under the [MIT LICENSE](https://github.com/pardnchiu/QuickUI/blob/main/LICENSE).

## Author

Just [open an issue](https://github.com/pardnchiu/QuickUI/issues/new) to share an idea.

<a href="https://github.com/pardnchiu/QuickUI/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=pardnchiu/QuickUI&cache_bust=2026-10-03" alt="QuickUI contributors" />
</a>

***

©️ 2024 [邱敬幃 Pardn Chiu](https://www.linkedin.com/in/pardnchiu)

---

Source: https://quickui.pardn.io/getting-started.md

# Getting Started

This page covers how to install QuickUI and bind your first data object to a page.

## Prerequisites

| Item | Requirement |
|---|---|
| Browser | ES2022, `Proxy`, `IntersectionObserver` and `structuredClone` support |
| HTTP server | Required when using external `i18n` files or `<temp :path>`; `fetch` fails under `file://` |
| Node.js | Only needed when building from source |

## Installation

### CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@pardnchiu/quickui@latest/dist/QuickUI.js"></script>
```

Loading the script registers three globals: `QUI`, `_` and `$`. See [Global Helpers](/global-helpers).

### npm

```bash
npm i @pardnchiu/quickui
```

### ESM

```javascript
import { QUI } from "@pardnchiu/quickui";
```

`package.json` points `module` at `dist/QuickUI.esm.js`, so bundlers resolve the bare package name to the ESM build. The ESM build is the same code as the CDN build with `window.QUI` exported at the end, so importing it still registers the globals.

### From Source

```bash
git clone https://github.com/pardnchiu/QuickUI.git
cd QuickUI
npm install
npm run build:once
```

`build:once` runs `tsc` to bundle `src/` into `src/QuickUI.debug.js`, then terser produces `dist/QuickUI.js` and `dist/QuickUI.esm.js`.

## Your First App

```demo
<div id="app">
  <h1>{{ title }}</h1>
  <p>{{ description }}</p>
</div>

<script src="https://cdn.jsdelivr.net/npm/@pardnchiu/quickui@latest/dist/QuickUI.js"></script>
<script>
  const app = new QUI({
    id: "app",
    data: {
      title: "Hello QuickUI",
      description: "A lightweight frontend framework",
    },
  });
</script>
```

`id` points to an existing element whose content becomes the template. Changing `app.data.title` later re-renders the page about 300 ms after the change.

## Next Steps

| Goal | Page |
|---|---|
| Learn the template syntax | [Text Binding](/text-binding), [Conditional Rendering](/conditional-rendering), [Loop Rendering](/loop-rendering) |
| Handle user input | [Event Binding](/event-binding), [Two-way Binding](/two-way-binding) |
| Look up every option | [Constructor Options](/constructor-options) |

---

Source: https://quickui.pardn.io/architecture.md

# Architecture

This page shows how QuickUI's modules are layered and where each one lives in the source, in a single overview diagram.

## System Overview

```mermaid
graph TB
    T["Template: element referenced by id / render()"] --> V["vDOM: :for → :if → :path → {{ }}"]
    D["data (Proxy)"] -->|"set triggers"| L["Lifecycle: 300 ms debounce"]
    L --> V
    I["i18n locale data"] --> V
    V --> P["diff → Patch[]"]
    P -->|"requestAnimationFrame"| R["Real DOM"]
    R --> O["Listeners: lazyload / temp-svg"]
```

## Layers

| Layer | Source | Responsibility |
|---|---|---|
| Entry | `src/model` (`QUI.ts`) | Creates the instance, loads i18n, wraps reactive data, applies patches, handles attribute and event binding |
| Virtual DOM | `src/model` (`vDOM.ts`) | Turns elements into `tag` / `props` / `children` / `data`, expands `:for`, `:if`, `:path`, replaces `{{ }}`, produces patches |
| Lifecycle | `src/model` (`Lifecycle.ts`) | Wraps the timing of the initial render and updates, runs `when` hooks, debounces updates by 300 ms |
| Utilities | `src/function` | `createReactiveObject`, `htmlParser`, `createElement`, `getElement`, `calc`, `dateFormat` and more |
| Listeners | `src/listener` | `IntersectionObserver`-driven image lazy loading and SVG inlining |
| Shared constants | `src/*.ts` | Global aliases, regular expressions, directive names, the effect CSS injected into the page |

`tsc` concatenates every file into one script, `src/QuickUI.debug.js`, through the `outFile` setting in `tsconfig.json`; there are no module imports. Public names are attached to the global object as `window.QUI`, `window._` and `window.$`.

## Cross-cutting Principles

| Principle | Implementation |
|---|---|
| Zero dependencies | Only native browser APIs (`Proxy`, `fetch`, `IntersectionObserver`, `requestAnimationFrame`) |
| The template is the DOM | Templates are plain HTML on the page with no compile step; every render rebuilds the vDOM from a copy of the original template |
| Data snapshots | Each render takes a snapshot with `JSON.parse(JSON.stringify(data))`, so functions, `Date` objects and `undefined` never reach the template |
| Batched writes | Patches are always applied inside `requestAnimationFrame` |

## Further Reading

- Render flow in detail: [Rendering Pipeline](/rendering-pipeline)
- Change detection: [Reactive Data](/reactive-data)
- Per-module diagrams: [doc/architecture.md](https://github.com/pardnchiu/QuickUI/blob/main/doc/architecture.md)

---

Source: https://quickui.pardn.io/rendering-pipeline.md

# Rendering Pipeline

This page walks through the steps a render takes from template to real DOM, and the order in which patches are applied.

## Initialization

| Step | Behavior |
|---|---|
| 1 | Resolve the element by `id`; with no `id` but a `render` function, create a detached `<section class="QUIFragment">` |
| 2 | Clone the element as the original template and build the first vDOM from the unprocessed template as the diff baseline |
| 3 | When `render` is given, replace the template content with its output |
| 4 | Load `i18n` (string values are fetched); only then are `app.data`, `app.event` and `app.body` assigned |
| 5 | Enable the SVG and lazyload listeners according to `option`, create the `Lifecycle` and run the initial render |

If the element is missing, or neither `id` nor `render` is given, an error is logged to the console and the instance renders nothing.

## Each Render

| Stage | Behavior |
|---|---|
| Rebuild vDOM | Build a new vDOM from a copy of the original template, using a `JSON.parse(JSON.stringify(app.data))` snapshot as data |
| Expand directives | Process `:for` → `:if` → `<temp :path>`, then run `:for` and `:if` again on content inserted by `:path` |
| Replace text | Replace `{{ i18n.* }}` first, then every other `{{ }}` |
| Diff | Compare the old and new vDOM child by child using indexes, producing patches |
| Apply | Apply the patches inside `requestAnimationFrame`, then strip leftover `:if` attributes and handle [Render Effects](/effects) |

## Patch Types

| Type | Trigger | Action |
|---|---|---|
| `REMOVE` | The new tree has no node at that position | Removed from the deepest, last position first so indexes do not shift |
| `CREATE` | The old tree has no node | Create the element and append it to the parent |
| `APPEND` | The number of children grows | Insert at the matching index |
| `REPLACE` | The tag name differs at the same position | Replace with the new element |
| `PROP` | Every attribute of every new node | Dispatched by prefix to [attribute](/attribute-binding), [event](/event-binding) or [form](/two-way-binding) handling |
| `TEXT` | The text differs at the same position | Overwrite the text content |

`REMOVE` patches always run before every other patch.

## Edge Cases

| Situation | Result |
|---|---|
| Inserting at the front of a list | Diffing has no keys and aligns by index, so every item after the insertion point receives patches |
| `<script>` inside a template | Moved to `<head>` while the vDOM is built; skipped when an existing `<script>` has the same `src` or content |
| Values the snapshot cannot serialize | Functions, `Date`, `Map` and similar values are not available in templates; convert them to strings or numbers first |

---

Source: https://quickui.pardn.io/reactive-data.md

# Reactive Data

This page explains how `app.data` detects changes, when a re-render is triggered, and which writes do not trigger one.

## How It Works

The `data` option is wrapped recursively in a `Proxy` by `createReactiveObject`: reading a nested object returns a new Proxy, and a write whose new value differs from the old one (`!==`) tells the lifecycle to schedule an update.

```demo
<div id="app">
  <p>{{ count }} · {{ user.name }} · {{ LENGTH(items) }}</p>
  <button @click="update">Update</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { count: 0, user: { name: "Pardn" }, items: [] },
    event: {
      update: () => {
        app.data.count++;
        app.data.user.name = "Chiu";
        app.data.items.push("A");
      },
    },
    when: {
      updated: () => console.log("updated", app.data.count),
    },
  });
</script>
```

All three writes trigger an update; writes within 300 ms of each other are merged into one render.

## What Triggers an Update

| Write | Triggers |
|---|---|
| `app.data.key = value` (value changes) | Yes |
| Nested properties, array indexes, `push` / `splice` | Yes |
| Writing the same value | No |
| `delete app.data.key` | No, the Proxy does not trap deletion |
| Replacing `app.data = { ... }` | No, the replacement is not a Proxy |
| `once: true` | No, data is not wrapped and renders once |

## When to Access It

`app.data` is assigned only after i18n finishes loading; even without `i18n` it is deferred to the next microtask. Values written synchronously right after `new QUI()` land on a placeholder object and are lost. Read and write it inside the [`rendered` hook](/lifecycle) or an event handler.

## Template Lookup Rules

| Rule | Description |
|---|---|
| Paths | Use `.` for nested values, for example `{{ user.name }}` |
| Scope | The current `:for` item's data is searched first, then the root data |
| Missing value | The `{{ }}` placeholder stays on the page as written |
| Usable types | Strings, numbers, booleans, arrays, plain objects; functions and `Date` are lost in the snapshot |

---

Source: https://quickui.pardn.io/text-binding.md

# Text Binding

This page covers writing data into text with `{{ }}` and inserting HTML with `:html`.

## `{{ value }}`

```demo
<div id="app">
  <h1>{{ title }}</h1>
  <p>{{ user.name }} · {{ LENGTH(items) }} items</p>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", user: { name: "Pardn" }, items: [1, 2, 3] },
  });
</script>
```

| Rule | Description |
|---|---|
| Allowed characters | Letters, digits, underscores and `.`; may be wrapped in a [built-in function](/built-in-functions) |
| Whitespace | Both `{{title}}` and `{{ title }}` work |
| Missing value | `{{ title }}` stays on the page as written |
| Localization | `{{ i18n.key }}` reads the current locale, see [i18n](/i18n) |
| Position | Replaced only in text nodes; `{{ }}` inside plain attributes is left alone, use [Attribute Binding](/attribute-binding) for attributes |

## `:html`

```demo
<div id="app">
  <section :html="content"></section>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { content: "<b>bold</b> text" },
  });
</script>
```

`:html` writes the value to `innerHTML`; when no matching data exists, the attribute value itself is written. Content is not sanitized, so never pass unescaped user input, or the page is open to XSS.

---

Source: https://quickui.pardn.io/built-in-functions.md

# Built-in Functions

This page lists the five functions available inside `{{ }}` and the limits of each.

## Function List

| Function | Syntax | Result |
|---|---|---|
| `LENGTH()` | `{{ LENGTH(items) }}` | Length of an array or string; key count for objects |
| `CALC()` | `{{ CALC(price * 1.05) }}` | Arithmetic between a data value and a number literal |
| `UPPER()` | `{{ UPPER(name) }}` | Uppercase |
| `LOWER()` | `{{ LOWER(name) }}` | Lowercase |
| `DATE()` | `{{ DATE(timestamp, YYYY-MM-DD HH:mm) }}` | Formats a UNIX timestamp in seconds |

Function names must be uppercase and only one level is allowed; functions cannot be nested.

## `CALC()`

```demo
<div id="app">
  <p>{{ CALC(price * 1.05) }}</p>
  <p>{{ CALC(count + 1) }}</p>
</div>

<script>
  const app = new QUI({ id: "app", data: { price: 100, count: 1 } });
</script>
```

Supported operators: `+`, `-`, `*`, `/`.

## `UPPER()` / `LOWER()`

The value must be a string; a `null` or missing value throws a `TypeError` and aborts that render.

## `DATE()`

```demo
<div id="app">
  <p>{{ DATE(now, YYYY-MM-DD HH:mm:ss) }}</p>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { now: Math.floor(Date.now() / 1000) },
  });
</script>
```

| Token | Output |
|---|---|
| `YYYY` / `YY` | Four-digit / two-digit year |
| `MM` / `M` | Zero-padded / unpadded month |
| `DD` / `D` | Zero-padded / unpadded day |
| `HH` / `H` | 24-hour clock |
| `hh` / `h` | 12-hour clock |
| `mm` / `m`, `ss` / `s` | Minutes, seconds |
| `SSS` | Milliseconds |
| `A` / `a` | `AM` / `PM`, `am` / `pm` |
| `ddd` | Weekday; 星期一 when the browser language contains `zh`, otherwise the English abbreviation (Mon) |

The format string only accepts letters, digits, spaces, `-`, `:` and `,`; with `/` or `.` it is not recognized as `DATE()` and `{{ }}` stays as written.

---

Source: https://quickui.pardn.io/conditional-rendering.md

# Conditional Rendering

This page covers writing `:if`, `:else-if` and `:else`, the comparison operators available, and how conditions are evaluated.

## Basic Usage

```demo
<div id="app">
  <p :if="status == active">Active</p>
  <p :else-if="status == pending">Pending</p>
  <p :else>Disabled</p>
</div>

<script>
  const app = new QUI({ id: "app", data: { status: "active" } });
</script>
```

| Directive | Description |
|---|---|
| `:if` | Starts a condition group |
| `:else-if` / `:elif` | Must directly follow the previous condition element at the same level |
| `:else` | Shown when no earlier condition holds |

Only the first element whose condition holds is kept. When none holds and there is no `:else`, the whole group is removed. An `:else-if` or `:else` with no preceding `:if` is treated as a normal element and always shown.

## Comparison Operators

| Operator | Comparison | Example |
|---|---|---|
| None | Truthiness of the value | `:if="isLogin"` |
| `==` / `===` | Equal after converting to strings | `:if="status == active"` |
| `!=` / `!==` | Not equal after converting to strings | `:if="status != disabled"` |
| `>` / `<` | Numeric comparison | `:if="count > 0"` |
| `>=` / `<=` | Numeric comparison | `:if="count <= 100"` |

## Special Comparison Values

| Value | Holds with `==` when | Holds with `!=` when |
|---|---|---|
| `null` | The value is `null` or missing | The value exists |
| `true` | The value is truthy | The value is falsy |
| `false` | The value is falsy | The value is truthy |
| `empty` | The value is an empty string or missing | The value is not empty |

## Evaluation Rules

| Rule | Description |
|---|---|
| Right-hand side | Always a literal, never looked up in data; `count > max` compares against `"max"`, which becomes `0` |
| Negation | `!flag` is not supported; write `flag == false` |
| Compound conditions | `&&` and `||` are not supported; nest elements or precompute a boolean in data |
| Combined with `:for` | `:for` expands first, then each item evaluates `:if` on its own and can use the item variable |

```demo
<ul id="app">
  <li :for="user in users" :if="user.active == true">{{ user.name }}</li>
</ul>

<script>
  const app = new QUI({
    id: "app",
    data: {
      users: [
        { name: "Pardn", active: true },
        { name: "Chiu", active: false },
      ],
    },
  });
</script>
```

---

Source: https://quickui.pardn.io/loop-rendering.md

# Loop Rendering

This page explains how `:for` expands arrays and objects, and which variables are reachable inside a loop.

## Arrays

```demo
<ul id="app">
  <li :for="item in items">{{ item }}</li>
  <li :for="(item, index) in items">{{ index }}. {{ item }}</li>
</ul>

<script>
  const app = new QUI({ id: "app", data: { items: ["A", "B", "C"] } });
</script>
```

| Syntax | Variables |
|---|---|
| `item in list` | `item` is the element |
| `(item, index) in list` | Adds a zero-based `index` |

## Objects

```demo
<ul id="app">
  <li :for="(key, value) in user">{{ key }}: {{ value }}</li>
</ul>

<script>
  const app = new QUI({ id: "app", data: { user: { name: "Pardn", role: "Developer" } } });
</script>
```

The first variable is the key and the second is the value; with a single variable you only get the key.

## Scope

| Reachable | Description |
|---|---|
| Loop variables | `item`, `index` (or `key`, `value`) |
| Source collection | Read from root data under the same name, for example `items` |
| Root data | Looked up in `app.data` when the loop scope has no match |
| Outer loop variables | Not reachable; the inner body of a nested loop only sees its own variables and root data |

```demo
<div id="app">
  <div :for="group in groups">
    <h3>{{ group.name }}</h3>
    <p :for="member in group.members">{{ member }}</p>
  </div>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: {
      groups: [
        { name: "Frontend", members: ["Pardn", "Chiu"] },
        { name: "Backend", members: ["Ching-Wei"] },
      ],
    },
  });
</script>
```

The inner source path `group.members` may use the outer variable, but `{{ group.name }}` inside the inner element is not replaced.

---

Source: https://quickui.pardn.io/attribute-binding.md

# Attribute Binding

This page covers binding data to HTML attributes with the `:` or `q-` prefix, and how `:hide` is evaluated.

## Syntax

```demo
<div id="app">
  <a :href="link" :title="label">{{ label }}</a>
  <img :src="avatar" :alt="name" />
  <button q-data-id="userId">Edit</button>
  <a :href="/user/{{ userId }}">Profile</a>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: {
      link: "https://quickui.pardn.io",
      label: "Docs",
      avatar: "https://quickui.pardn.io/favicon.png",
      name: "QuickUI",
      userId: 42,
    },
    when: {
      rendered: () => [...$("app").children].forEach((e) => console.log(e.outerHTML)),
    },
  });
</script>
```

| Prefix | Description |
|---|---|
| `:` | Standard form, for example `:href` |
| `q-` | Equivalent form, for example `q-href`; useful for toolchains that reject `:` in attribute names |

The attribute value is first looked up as a data path; when nothing matches, the value itself is used. When the value contains `{{ }}`, only the first `{{ }}` is replaced and the surrounding text is kept. The original `:` attribute is removed afterwards.

## Dispatch Rules

| Attribute | Written as |
|---|---|
| `:id`, `:src`, `:alt`, `:href` | Element property |
| `:html` | `innerHTML`, see [Text Binding](/text-binding) |
| `:` prefix and the name matches a CSS property (such as `:width`, `:color`) | Written to `style`, see [Style Binding](/style-binding) |
| `:hide` | Sets `display: none` when truthy |
| `:lazyload` | See [Image Lazy Loading](/lazyload) |
| Anything else (such as `:title`, `:data-id`, `:value`) | `setAttribute` with the prefix stripped |

Names that match a CSS property always go to `style`: `<img :width="w">` sets the CSS `width`, not the `width` attribute.

## `:hide`

```demo
<div id="app">
  <div :hide="isHidden">Content</div>
  <button @click="toggle">Toggle</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { isHidden: false },
    event: {
      toggle: () => {
        app.data.isHidden = !app.data.isHidden;
      },
    },
    when: {
      updated: () => console.log(app.data.isHidden, $("app").children[0].outerHTML),
    },
  });
</script>
```

| Value | Result |
|---|---|
| `true`, non-zero numbers, non-empty strings | Hidden |
| `false`, `0`, `"0"`, empty string | Shown; the value is written as a `hide` attribute (for example `hide="false"`) |
| A key that does not exist in data | The attribute value itself (a non-empty string) is used, so the element is hidden |

The string `"false"` is truthy and also hides the element; use booleans.

Once hidden, setting the value back to a falsy one does not remove `display: none`, so the element stays hidden. Press Toggle twice in the preview above to reproduce it.

## Localized Attribute Values

Any attribute whose value is `i18n.key` is replaced with the translation for the current locale, for example `placeholder="i18n.search"`. Attributes only support single-level keys, see [i18n](/i18n).

---

Source: https://quickui.pardn.io/style-binding.md

# Style Binding

This page covers binding data straight to inline styles with `:[CSS property]`.

## Syntax

```demo
<div id="app">
  <button :width="width" :background-color="color">Save</button>
</div>

<script>
  const app = new QUI({ id: "app", data: { width: "120px", color: "#3498db" } });
</script>
```

Result:

```html
<button style="width: 120px; background-color: #3498db;">Save</button>
```

| Rule | Description |
|---|---|
| Name | A kebab-case CSS property name whose camelCase form exists on `element.style` |
| Value | The data value or the attribute value itself, including units, for example `"120px"` |
| Prefix | Only `:`; `q-width` does not reach `style` and sets the `width` attribute instead |
| `:animation` | Values `fade-in` and `expand` are not written to `style`; they are treated as [Render Effects](/effects) |

## Legacy Names

The forms below still work but are planned for removal in 1.0.0; see [Deprecations](/deprecations).

| Legacy | Use instead |
|---|---|
| `:bg-*` such as `:bg-color`, `:bg-image` | `:background-color`, `:background-image` |
| camelCase such as `:borderRadius`, `:backgroundColor` | `:border-radius`, `:background-color` |

---

Source: https://quickui.pardn.io/event-binding.md

# Event Binding

This page covers wiring DOM events to handlers in the `event` option with `@event`.

## Syntax

```demo
<div id="app">
  <button @click="save">Save</button>
  <input type="text" @input="typing" />
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { text: "" },
    event: {
      save: (e) => console.log("saved", app.data.text),
      typing: (e) => {
        app.data.text = e.target.value;
      },
    },
  });
</script>
```

| Prefix | Example | Description |
|---|---|---|
| `@` | `@click` | Standard form |
| `qe-` | `qe-click` | Equivalent form |

`@click="save"` becomes `element.onclick = app.event.save`, and the `@click` attribute is removed afterwards.

## Rules

| Rule | Description |
|---|---|
| Event name | Must be a native event with a matching `on*` property on the element (`click`, `input`, `change`, `submit`, `keyup` and so on); custom events never fire |
| Handler arguments | Only the `Event`; with a `function` declaration, `this` is the element |
| One handler per event | Assigned as a property, so an element keeps only one handler per event |
| Name lookup | The value is first looked up as a data path and the result is used as the handler name; otherwise the value itself is the name |
| Unknown name | `undefined` is assigned; clicking does nothing and no error is raised |
| `:@click` | Not supported; the attribute is removed and nothing is bound |

## Getting the Item Inside a Loop

Handlers do not receive the `:for` item, so put the identifier in a `data-*` attribute:

```demo
<ul id="app">
  <li :for="user in users">
    <button :data-id="user.id" @click="remove">Remove {{ user.id }}</button>
  </li>
</ul>

<script>
  const app = new QUI({
    id: "app",
    data: { users: [{ id: 1 }, { id: 2 }] },
    event: {
      remove: (e) => {
        const id = +e.target.dataset.id;
        app.data.users = app.data.users.filter((u) => u.id !== id);
      },
    },
  });
</script>
```

## Using Handlers Outside QuickUI

`app.event` keeps the original function map, so handlers can be assigned to elements you create yourself:

```javascript
const button = document.createElement("button");
button.onclick = app.event.save;
app.body.append(button);
```

---

Source: https://quickui.pardn.io/two-way-binding.md

# Two-way Binding

This page explains how `:model` writes form input back into data.

## Syntax

```demo
<div id="app">
  <input type="text" :model="username" />
  <p>Hello, {{ username }}</p>
</div>

<script>
  const app = new QUI({ id: "app", data: { username: "" } });
</script>
```

## Behavior per Element

| Element | Events | Value written to `app.data[key]` |
|---|---|---|
| Text `<input>`, `<textarea>` | `keyup`, `change` | `value`, `""` when empty |
| `<select>` | `change` | The selected option's `value` |
| `<input type="checkbox">`, `<input type="radio">` | `change` | Values of every checked input on the page with the same `name` and `type`, joined with `,` |

`:model` on any other element is ignored.

---

Source: https://quickui.pardn.io/i18n.md

# i18n

This page covers defining locales, referencing translations in text and attributes, and switching languages.

## Defining Locales

```demo
<div id="app">
  <h1>{{ i18n.title }}</h1>
  <input placeholder="i18n.search" />
  <button @click="toEn">English</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    i18n: {
      zh: { title: "歡迎", search: "搜尋" },
      en: "/i18n/en.json",
    },
    i18nLang: "zh",
    event: {
      toEn: () => app.lang("en"),
    },
  });
</script>
```

| Option | Description |
|---|---|
| `i18n` | Maps a locale code to an object, or to the URL of a JSON file |
| `i18nLang` | Initial locale, defaults to `"zh"` |

String values are fetched before the initial render; when loading fails or the response is not 2xx, that locale becomes an empty object and rendering continues.

## Referencing Translations

| Location | Syntax | Key rules | When missing |
|---|---|---|---|
| Text | `{{ i18n.menu.home }}` | Nested keys with `.` | Shows the key itself (`menu.home`) |
| Attribute value | `placeholder="i18n.search"` | Single-level keys only | Keeps the original string `i18n.search` |

The attribute value must be exactly `i18n.key` with no other text mixed in.

## Switching Languages

`app.lang(code)` updates the current locale and triggers a re-render; it does nothing when `code` is not in `i18n`. Instances created with `once: true` have non-reactive data, so switching does not re-render.

## Reserved Keys

Locale data lives in `app.data.quickui_i18n` and the current locale in `app.data.quickui_i18nLang`. Do not use these two names in your own `data`.

---

Source: https://quickui.pardn.io/lifecycle.md

# Lifecycle Hooks

This page covers when each hook in the `when` option fires, what it receives, and how to cancel a render.

## Syntax

```demo
<div id="app">
  <p>{{ count }}</p>
  <button @click="add">+1</button>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { count: 0 },
    event: {
      add: () => app.data.count++,
    },
    when: {
      beforeRender: () => {},
      rendered: (sec) => console.log("rendered in", sec),
      beforeUpdate: () => app.data.count < 10,
      updated: (sec) => console.log("updated in", sec),
    },
  });
</script>
```

## Hook List

| Hook | Fires | Argument | Returning `false` |
|---|---|---|---|
| `beforeRender` | Before the initial render | None | Cancels the initial render; the raw template stays on screen |
| `rendered` | After the initial render reaches the DOM | Duration in seconds | No effect |
| `beforeUpdate` | After a data change and the 300 ms debounce | None | Cancels this update |
| `updated` | After the update reaches the DOM | Duration in seconds | No effect |
| `beforeDestroy` | Never fires in the current version | None | None |
| `destroyed` | Never fires in the current version | None | None |

`beforeDestroy` and `destroyed` are accepted, but `QUI` has no public destroy method, so they are never called.

## Rules

| Rule | Description |
|---|---|
| Cancelling | Only a synchronous `false` cancels; an `async` function returns a Promise and cannot cancel |
| Update debounce | Multiple writes within 300 ms trigger `beforeUpdate` / `updated` once |
| Reading data | `app.data` is ready from `rendered` onward, see [Reactive Data](/reactive-data) |

## Legacy Forms

Hooks placed in a `lifecycle` object, at the top level of the options, or named in snake_case such as `before_render`, `before_update` and `before_destroy` still work but are planned for removal in 1.0.0; see [Deprecations](/deprecations).

---

Source: https://quickui.pardn.io/block-insertion.md

# Block Insertion

This page covers loading an external HTML file into the template with `<temp :path>`.

## Syntax

```demo
<div id="app">
  <temp :path="/components/header.html"></temp>
  <temp :path="footerUrl"></temp>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", footerUrl: "/components/footer.html" },
  });
</script>
```

The content of `header.html` replaces the `<temp>` element itself; inserted content can use `{{ }}`, `:for`, `:if` and every other directive.

## Rules

| Rule | Description |
|---|---|
| Tag | `:path` only works on `<temp>` |
| Path | Looked up as a data key first, otherwise used as the URL |
| When it loads | Fetched again on every render; caching is left to the browser HTTP cache |
| Order | Loaded after `:for` and `:if`, then `:for` and `:if` run again on the inserted content |
| Environment | Requires an HTTP server; `fetch` fails under `file://` |

## Failure Cases

| Case | Result |
|---|---|
| A 404 or other error status | The status is not checked, so the error page's body is inserted |
| Network error or CORS rejection | `fetch` throws, that render stops, and the page keeps the previous result |

Before deploying, make sure every `:path` points to a file that exists.

---

Source: https://quickui.pardn.io/lazyload.md

# Image Lazy Loading

This page covers how `:lazyload` loads an image only when it enters the viewport, and which fallback image is used on failure.

## Syntax

```demo
<div id="app">
  <img :lazyload="photo" />
  <img :lazyload="photo" :effect="circle" />
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { photo: "https://example.com/photo.jpg" },
  });
</script>
```

| Stage | Behavior |
|---|---|
| Initial render | `src` is set to a transparent placeholder; with `:effect="circle"` a spinning loader is used instead |
| Enters the viewport | `IntersectionObserver` fires, sends `HEAD` then `GET`, and sets `src` to a blob URL |
| Afterwards | The `lazyload` and `effect` attributes are removed |
| Later renders | Already loaded images get `src` directly and are not observed again |

`<img>` elements already on the page with a `lazyload="url"` attribute, even if QuickUI did not render them, are observed too when the listener is created.

## Failure Handling

| Case | `src` |
|---|---|
| A `TypeError` with the message `Load failed` (Safari's CORS failure) or an image `Event` | The original URL is used directly |
| Any other error (including 404, and CORS failures in browsers with a different message such as Chrome) | `https://cdn.jsdelivr.net/gh/pardnchiu/PDRenderKit@latest/static/image/404.svg` |

For cross-origin images, make sure the server sends CORS headers, otherwise Chrome shows the 404 fallback.

## Disabling

```javascript
new QUI({ id: "app", option: { lazyload: false } });
```

With it disabled, no listener is created; using `:lazyload` in the template then throws because the observer does not exist, so use `:src` instead.

---

Source: https://quickui.pardn.io/svg-inline.md

# SVG Inlining

This page covers how `<temp-svg>` swaps an external SVG file for an inline `<svg>` element, so CSS can style it.

## Syntax

```demo
<div id="app">
  <temp-svg :src="icon" class="icon" @click="close"></temp-svg>
  <temp-svg src="/icons/menu.svg"></temp-svg>
</div>

<script>
  const app = new QUI({
    id: "app",
    data: { icon: "/icons/close.svg" },
    event: { close: () => {} },
  });
</script>
```

| Stage | Behavior |
|---|---|
| Render | `<temp-svg :src>` sets `src` and hands the element to an `IntersectionObserver` |
| Enters the viewport | The SVG text is fetched and its first child element is parsed |
| Replacement | The new `<svg>` takes the original element's `id`, every class and `onclick`, is inserted in its place, and `<temp-svg>` is removed |
| Failure | The content of `<temp-svg>` becomes `☒` |

`<temp-svg>` elements already on the page with a static `src` are processed too when the listener is created.

## Rules

| Rule | Description |
|---|---|
| Carried over | Only `id`, classes and `onclick`; other attributes and events are not transferred |
| File content | Only the first element in the response is used and it must be `<svg>`; sibling elements after it are discarded |
| Cross-origin | Requires CORS headers |

## Disabling

```javascript
new QUI({ id: "app", option: { svg: false } });
```

With it disabled, no listener is created; using `<temp-svg :src>` in the template then throws because the observer does not exist.

---

Source: https://quickui.pardn.io/effects.md

# Render Effects

This page covers how the `effect` and `mask` attributes on the root element provide fade-in, expand and skeleton loading effects on the first render.

## Syntax

```demo
<div id="app" effect="fade-in">
  <p>{{ message }}</p>
</div>

<script>
  const app = new QUI({ id: "app", data: { message: "Hello QuickUI" } });
</script>
```

QuickUI injects the matching CSS into `<head>` when it loads. After the render is applied, the root element gets the `show` class to start the transition, and 300 ms later the effect attributes and the `show`, `fade-in`, `expand` and `loading-block` classes are removed.

## Available Effects

| Attribute | Effect |
|---|---|
| `effect="fade-in"` | Opacity 0 → 1 over 0.3 s |
| `effect="expand"` | Height grows from 0 to the content height (sets `min-height` from `scrollHeight`) over 0.3 s |
| `mask="1"` | Covers the content with a grey gradient skeleton animation that fades out after rendering |

`effect` can also be written as `:effect`; legacy forms such as `animation="fade-in"` are planned for removal in 1.0.0, see [Deprecations](/deprecations).

## Rules

| Rule | Description |
|---|---|
| Target | Only the root element (the one referenced by `id`) |
| How often | The attributes are removed after the first render, so later updates do not replay them |
| `mask="true"` | The injected CSS makes its overlay transparent from the start, so nothing shows; use `mask="1"` |
| Image loader | `:effect="circle"` on `<img>` belongs to [Image Lazy Loading](/lazyload) |

---

Source: https://quickui.pardn.io/constructor-options.md

# Constructor Options

This page lists every option accepted by `new QUI(options)`, with its type, default, and how options interact.

## Type

```typescript
new QUI(options: {
  id?: string;
  render?: () => string;
  data?: Record<string, any>;
  event?: Record<string, Function>;
  i18n?: Record<string, string | object>;
  i18nLang?: string;
  once?: boolean;
  option?: { svg?: boolean; lazyload?: boolean };
  when?: {
    beforeRender?: () => boolean | void;
    rendered?: (sec: number) => void;
    beforeUpdate?: () => boolean | void;
    updated?: (sec: number) => void;
    beforeDestroy?: () => boolean | void;
    destroyed?: (sec: number) => void;
  };
})
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | None | ID of the element used as template and mount point |
| `render` | `() => string` | None | Returns a [Render Shorthand](/render-shorthand) string |
| `data` | `object` | `{}` | Reactive data, see [Reactive Data](/reactive-data) |
| `event` | `object` | `{}` | Event handlers, see [Event Binding](/event-binding) |
| `i18n` | `object` | None | Locale objects or JSON URLs, see [i18n](/i18n) |
| `i18nLang` | `string` | `"zh"` | Initial locale |
| `once` | `boolean` | `false` | When `true`, data is not wrapped in a Proxy and renders once |
| `option.svg` | `boolean` | `true` | Enables [SVG Inlining](/svg-inline) |
| `option.lazyload` | `boolean` | `true` | Enables [Image Lazy Loading](/lazyload) |
| `when` | `object` | None | [Lifecycle Hooks](/lifecycle) |

## Combining `id` and `render`

| `id` | `render` | Result |
|---|---|---|
| Set | Not set | The element's content is the template and the element is updated in place |
| Set | Set | The output of `render()` replaces the element's content and becomes the template |
| Not set | Set | A detached `<section class="QUIFragment">` is created; get the result with [`fragment()`](/instance-api) |
| Not set | Not set | An error is logged and the instance does not render |
| Points to a missing element | Any | An error is logged and the instance does not render |

## Interactions

| Combination | Result |
|---|---|
| `once: true` + `app.lang()` | The locale value changes but nothing re-renders |
| `option.lazyload: false` + `:lazyload` in the template | Throws |
| `option.svg: false` + `<temp-svg :src>` in the template | Throws |
| No `when` | Hooks are read from a `lifecycle` object, then from the top level of the options (legacy forms, see [Deprecations](/deprecations)) |

---

Source: https://quickui.pardn.io/instance-api.md

# Instance API

This page lists the methods and properties available on the instance returned by `new QUI()`.

## Methods

| Method | Signature | Description |
|---|---|---|
| `lang` | `lang(code: string): void` | Switches the locale and triggers a re-render; ignored when `code` is not in `i18n` |
| `fragment` | `fragment(): Promise<DocumentFragment>` | Renders once more and returns a copy of the root element's child nodes |

### `fragment()`

```demo
<script>
  const card = new QUI({
    render: () => `div.card[ h2[ "{{title}}" ] ]`,
    data: { title: "QuickUI" },
    when: {
      rendered: async () => {
        document.body.append(await card.fragment());
      },
    },
  });
</script>
```

| Rule | Description |
|---|---|
| Rendering | Runs the full template processing once, without calling `beforeUpdate` / `updated` |
| Text nodes | Leading and trailing whitespace is trimmed |
| Return value | A copy; changing it does not affect the instance and it receives no further updates |
| When to call | After `rendered`, so data is ready |

## Properties

| Property | Type | Description |
|---|---|---|
| `data` | `Proxy` | Reactive data, see [Reactive Data](/reactive-data) |
| `event` | `Record<string, Function>` | The original `event` option object |
| `body` | `Element` | The mounted root element; the `QUIFragment` section when there is no `id` |
| `isScheduled` | `boolean` | `true` while patches are queued in `requestAnimationFrame` and not yet applied |
| `lazyloadObserver` | `IntersectionObserver` | The shared image lazy-loading observer; `undefined` when lazyload is disabled |

`data`, `event` and `body` are assigned only after i18n finishes loading.

---

Source: https://quickui.pardn.io/render-shorthand.md

# Render Shorthand

This page covers the shorthand string format returned by the `render` option, and which directives it can and cannot express.

## Format

```text
tag#id.class1.class2(key: "value", key2: "value")[ children ]
```

| Part | Description |
|---|---|
| `tag` | Tag name, required |
| `#id`, `.class` | Optional; multiple classes allowed |
| `( ... )` | Attributes, `key: "value"` separated by commas or whitespace |
| `[ ... ]` | Children: nested elements or double-quoted text, may span lines |
| `"text"` | Parsed with `innerHTML`, so HTML entities work |

```demo
<div id="app"></div>

<script>
  const app = new QUI({
    id: "app",
    data: { title: "QuickUI", link: "https://quickui.pardn.io" },
    event: { open: () => {} },
    render: () => `
      section.hero[
        h1[ "{{title}}" ]
        a(q-href: "link", qe-click: "open")[ "Docs" ]
      ]
    `,
  });
</script>
```

## Whitespace

All whitespace inside double quotes is removed, attribute values included. Use an HTML entity when you need a space:

```text
p[ "Hello World" ]
p[ "Hello&#32;World" ]
```

The first line renders HelloWorld and the second renders Hello World.

## Available Directives

Attribute names only accept letters, digits, `-` and `_`, so directives starting with `:` or `@` cannot be written.

| Feature | Shorthand form |
|---|---|
| Text interpolation | `"{{title}}"` |
| Attribute binding | `q-` prefix, for example `q-href`, `q-html`, `q-hide` |
| Events | `qe-` prefix, for example `qe-click` |
| `:for`, `:if`, `:model`, `<temp :path>` | Not supported |

For loops or conditions, use `id` with an HTML template instead.

---

Source: https://quickui.pardn.io/global-helpers.md

# Global Helpers

This page covers `_` and `$`, the two DOM helpers QuickUI attaches to the global object when it loads.

## `$(selector)`

Returns a single element, `HTMLElement | null`.

```demo
<div id="app" class="card">
  <input name="email" />
  <button>Send</button>
</div>

<script>
  console.log($("#app").id);
  console.log($("app").id);
  console.log($(".card").className);
  console.log($("input[name=email]").name);
  console.log($("button").textContent);
</script>
```

| Input | Lookup |
|---|---|
| Starts with `#` | `getElementById` with `#` removed |
| Contains `.`, `[` or `]` | `querySelector` |
| Anything else | `getElementById` first, then `querySelector` |

Only the first match is returned; use `document.querySelectorAll` when you need several.

## `_(selector, attributes?, children?)`

Creates an element from CSS selector syntax.

```demo
<script>
  const card = _("div#card.box.shadow", { title: "Card", color: "red" }, [
    _("h2", "Title"),
    "plain text",
  ]);
  const img = _("img", "/logo.png");
  const text = _("temp", "text only");
  document.body.append(card);
  console.log(card.outerHTML);
  console.log(img.outerHTML);
  console.log(text.textContent);
</script>
```

| Argument | Description |
|---|---|
| `selector` | `tag#id.class`; must start with a tag or `undefined` is returned; `temp` creates a `DocumentFragment` |
| `attributes` | An object, see the table below |
| `children` | A string, number or array; with a single argument, a string / number / array is treated as `children` and an object as `attributes` |

| `attributes` key | Written as |
|---|---|
| `value`, `innerText`, `innerHTML`, `textContent`, `contentEditable` | Element property |
| `color`, `backgroundColor`, `width`, `height`, `display`, `float` | `style` |
| Anything else | `setAttribute`; skipped when the value is `null` or `undefined` |

| `children` type | Result |
|---|---|
| String or number | Written to `innerHTML`; `img` and `source` get `src` instead; `temp` creates a text node |
| Array | Appended in order; strings and numbers become text nodes, `Element` values are appended as is, anything else is skipped |

String `children` are written with `innerHTML`, so never pass unescaped user input.

---

Source: https://quickui.pardn.io/deprecations.md

# Deprecations

This page lists forms that still work today but are planned for removal in 1.0.0, along with their replacements.

From 1.0.0 only camelCase names and the `when` object are maintained, to keep the syntax consistent and the bundle small. No public API has been removed yet.

## Lifecycle

| Planned removal | Use instead |
|---|---|
| A `lifecycle: { ... }` object | `when: { ... }` |
| Hooks at the top level of the options (such as `new QUI({ rendered() {} })`) | Move them into `when` |
| `before_render` | `beforeRender` |
| `before_update` | `beforeUpdate` |
| `before_destroy` | `beforeDestroy` |

```javascript
new QUI({
  id: "app",
  when: {
    beforeRender: () => {},
  },
});
```

## Style Binding

| Planned removal | Use instead |
|---|---|
| `:bg-*` such as `:bg-color`, `:bg-image`, `:bg-size` | `:background-color`, `:background-image`, `:background-size` |
| camelCase names such as `:borderRadius`, `:backgroundColor` | `:border-radius`, `:background-color` |
| `:box-sahdow` (legacy misspelled name) | `:box-shadow` |

Standard kebab-case CSS property names are unaffected; see [Style Binding](/style-binding).

## Render Effects

| Planned removal | Use instead |
|---|---|
| `animation="fade-in"` and `animation="expand"` on the root element | `effect="fade-in"` and `effect="expand"` |

See [Render Effects](/effects).