Build a tiny reactive UI

A tiny framework in one page

In this lesson you build a very small UI framework. A UI framework is code that keeps a web page in step with your data. React and Vue are big ones. Yours fits on one page. It uses ideas from these earlier lessons:

• Closures, Proxy, and Reflect.
• The observer pattern and state management.
• Microtasks.
• Changing the DOM and MutationObserver.
• Delegation and event delegation.
• App architecture.

The framework has four small parts:

• a reactive function that notices every change to the state;
• an h function that describes a piece of the page as a plain object;
• a patch function that updates the real page;
• one click listener that handles every button.

It can't replace React, Vue, Svelte, or Solid. Its job is to show you the loop those tools run for you.

Two later lessons build on this one. Build a jQuery-style library shows how to package small tools like these. XSS shows what goes wrong when a page shows user text in an unsafe way.

The page should update whenever the state changes. So the framework must notice every change. It does this with a Proxy. A Proxy is an object that stands in front of another object. Every read and every write goes through the Proxy first. A function the Proxy runs for one kind of action is called a trap:

• The get trap runs on every read, like state.count.
• The set trap runs on every write, like state.count = 1.

Inside set, Reflect.set does the normal write. Then the trap calls scheduleRender(). To render means to build the page again from the state.

We don't want one render for every write. So scheduleRender uses queueMicrotask. It runs a function as a microtask: a short job that runs right after the current code finishes. A flag called queued remembers that a render is already waiting.

1const cache = new WeakMap();2let queued = false;3let renders = 0;4const writes = [];5 6function reactive(target) {7  const wrap = (value) => {8    if (typeof value !== "object" || value === null) return value;9    if (cache.has(value)) return cache.get(value);10    const proxy = new Proxy(value, {11      get(target, property, receiver) {12        return wrap(Reflect.get(target, property, receiver));13      },14      set(target, property, value, receiver) {15        writes.push(String(property));16        const ok = Reflect.set(target, property, value, receiver);17        if (ok) scheduleRender();18        return ok;19      },20    });21    cache.set(value, proxy);22    return proxy;23  };24  return wrap(target);25}26 27function scheduleRender() {28  if (queued) return;29  queued = true;30  queueMicrotask(() => {31    queued = false;32    renders += 1;33    console.log("render " + renders + ": " + state.count + "/" + state.user.name + "/" + state.items.join("|"));34  });35}36 37const state = reactive({ count: 0, user: { name: "Ada" }, items: [] });38state.count += 1;39state.user.name = "Grace";40state.items.push("mutated");41state.items = ["replaced"];42console.log("sync renders " + renders);43queueMicrotask(() => {44  console.log("after microtask " + renders);45  console.log(writes.join(","));46});

Here are the important lines:

• Line 10 makes the Proxy.
• Line 14 is the set trap. It runs on every write.
• Line 17 asks for a render.
• Line 28 stops early when a render is already queued.
• Lines 38 to 41 make four kinds of write: a plain property, a property of a nested object, an array push, and a whole new array. Each one reaches a set trap.
• Line 42 prints sync renders 0. No render has happened yet.
• The render runs next. It prints render 1: 1/Grace/replaced. Then lines 43 and 44 print after microtask 1 and the list of written names, count,name,0,length,items.

The step-through below runs a very similar program. It also renders once at the start, before any writes.

1const cache = new WeakMap();Run2let renderQueued = false;3let renderCount = 0;4 5function reactive(target) {6  const wrap = (value) => {7    if (typeof value !== "object" || value === null) return value;8    if (cache.has(value)) return cache.get(value);9    const proxy = new Proxy(value, {10      get(target, property, receiver) {11        return wrap(Reflect.get(target, property, receiver));12      },13      set(target, property, value, receiver) {14        const ok = Reflect.set(target, property, value, receiver);15        if (ok) scheduleRender();16        return ok;17      },18    });19    cache.set(value, proxy);20    return proxy;21  };22  return wrap(target);23}24 25function scheduleRender() {26  if (renderQueued) return;27  renderQueued = true;28  queueMicrotask(() => {29    renderQueued = false;30    render();31  });32}33 34function render() {35  renderCount += 1;36  console.log("render " + renderCount);37}38 39const state = reactive({ count: 0, profile: { name: "Ada" }, items: [] });40render();41state.count += 1;42state.profile.name = "Grace";43state.items.push("Learn diffing");44state.items = ["Ship tiny UI"];45queueMicrotask(() => console.log("final renders " + renderCount));

The observer pattern lesson showed signals. A signal remembers exactly which code read it. When it changes, only that code runs again. Our Proxy version is simpler: any write makes the whole view render again. It is easier to build and to follow, but it can do more work than needed.

The next example has no Proxy. It keeps a set of listeners: functions to call after each change.

1const listeners = new Set();2const state = { todos: [{ title: "Read", done: false }] };3 4function subscribe(listener) {5  listeners.add(listener);6  return () => listeners.delete(listener);7}8function setDone(done) {9  state.todos[0].done = done;10  for (const listener of listeners) listener();11}12function openCount() {13  return state.todos.filter((todo) => !todo.done).length;14}15 16const stop = subscribe(() => console.log("open " + openCount()));17setDone(true);18stop();19setDone(false);

• Line 1 makes an empty Set for the listeners.
• Line 5 adds a listener. Line 6 returns a function that removes it again.
• Line 9 changes the todo. Line 10 then calls every listener.
• Line 12, openCount(), counts the todos that are not done.
• Line 16 adds a listener and keeps the remove function in stop.
• Line 17 marks the todo done. The listener prints open 0.
• Line 18 calls stop(). So line 19 changes the todo, but nothing prints.

Calling stop() matters. A screen that is gone but still listening keeps running code. It also keeps its data in memory.

1let queued = false;2let renders = 0;3function schedule() {4  if (queued) return;5  queued = true;6  queueMicrotask(() => {7    queued = false;8    renders += 1;9    console.log("render " + renders);10  });11}12schedule();13schedule();14setTimeout(() => schedule(), 0);15setTimeout(() => console.log("total " + renders), 20);

• Lines 12 and 13 call schedule() twice in a row. The second call sees queued on line 4 and stops. So there is one render: render 1.
• Line 14 calls schedule() from a timer. setTimeout runs its function later, after the first render has finished. By then queued is false again, so it prints render 2.
• Line 15 runs last and prints total 2.

So the queued flag only joins writes made in the same run of code.

A view is a function that takes the state and returns a description of the page. It doesn't touch the real page.

The description is built with a small helper, h(tag, props, ...children). It returns a plain object with three fields:

• tag: the element name, like "h2".
• props: the element's attributes, like { class: "todo-card" }.
• children: what goes inside it, as text or more of these objects.

This plain object is a virtual node: a description of one element, not the element itself. A virtual node with children inside it is a virtual tree. The ...children part collects all the remaining arguments into an array. Making these objects is cheap and changes nothing on the page. Later, two of them are easy to compare.

1function h(tag, props = {}, ...children) {2  return { tag, props, children: children.flat() };3}4 5function view(state) {6  return h(7    "section",8    { class: "todo-card" },9    h("h2", {}, "Count: ", state.count),10    h("button", { type: "button", "data-action": "increment" }, "+1"),11    h("ul", {}, state.items.map((item) => h("li", {}, item.title)))12  );13}14 15const state = { count: 1, items: [{ title: "Render with text nodes" }] };16console.log(JSON.stringify(view(state), null, 2));

• Line 1 is the h helper.
• Line 5 starts the view. It takes the state.
• Line 9 describes a heading. Its children are the text "Count: " and the count.
• Line 10 describes a button. Its data-action attribute names a command, "increment". The button holds a name, not a function. You'll see who reads that name in the event section.
• Line 11 uses map to describe one li for each item.
• Line 16 prints the whole tree as JSON. It is all plain objects. No page elements exist yet.

Mounting means building the real page elements from the tree for the first time. The function below does it:

• Text and numbers become Text nodes with document.createTextNode. A Text node shows its text exactly as written. The browser never reads it as HTML.
• Other nodes become elements with document.createElement. Their props become attributes, and their children are built the same way.

User text is never pasted into innerHTML, which would read it as HTML.

1function createDom(vnode) {2  if (typeof vnode === "string" || typeof vnode === "number") {3    return document.createTextNode(String(vnode));4  }5  const element = document.createElement(vnode.tag);6  for (const [name, value] of Object.entries(vnode.props ?? {})) {7    element.setAttribute(name, String(value));8  }9  for (const child of vnode.children) element.append(createDom(child));10  return element;11}12 13const userText = "<img src=x onerror=alert(1)>";14const tree = { tag: "p", props: {}, children: ["Hello ", userText] };15const root = document.querySelector("#app");16root.replaceChildren(createDom(tree));17console.log(root.textContent);18console.log(root.querySelector("img"));

• Lines 2 and 3 turn a string or number into a Text node.
• Line 9 builds each child and adds it to the element.
• Line 13 is user text that looks like an image tag.
• Line 16 builds the tree and puts it into #app.
• Line 17 prints the text, angle brackets and all: Hello <img src=x onerror=alert(1)>.
• Line 18 prints null. No image element was made.

1const user = {2  name: "<img src=x onerror=alert(1)>",3  link: "javascript:alert(1)",4};5const label = document.createElement("p");6label.textContent = user.name;7const link = document.createElement("a");8const url = new URL(user.link, "https://example.test/");9if (url.protocol === "https:") link.href = url.href;10else link.textContent = "Blocked link";11console.log(label.textContent);12console.log(link.textContent);

• Line 6 sets textContent. That sets plain text, never HTML. So the angle brackets stay text.
• Line 8 reads the link with new URL.
• Line 9 sets href only for https: links. This link starts with javascript:, which would run code when clicked. So line 10 sets the text Blocked link instead.
• Lines 11 and 12 print the name as plain text, then Blocked link.

Don't write a loop that copies every user value onto an element as an attribute. An attribute like onclick runs code, and an unchecked link can too.

The simplest render throws away the whole page and builds it again. That is easy, but the browser keeps some things on each element, and they are lost:

• which input has the cursor (the focus);
• which text is selected;
• how far a box is scrolled;
• whether a video is playing;
• text typed into an input that the state doesn't store.

So instead, a patch function compares the old virtual tree with the new one. Comparing two trees is called diffing. Then patch changes the existing page elements only where the trees differ, and keeps every element it can.

1function patch(oldVNode, newVNode, domNode) {2  if (typeof oldVNode !== "object" || typeof newVNode !== "object") {3    if (String(oldVNode) !== String(newVNode)) domNode.nodeValue = String(newVNode);4    return domNode;5  }6 7  if (oldVNode.tag !== newVNode.tag) {8    const replacement = createDom(newVNode);9    domNode.replaceWith(replacement);10    return replacement;11  }12 13  updateProps(domNode, oldVNode.props, newVNode.props);14  const oldChildren = oldVNode.children;15  const newChildren = newVNode.children;16  const shared = Math.min(oldChildren.length, newChildren.length);17 18  for (let index = 0; index < shared; index += 1) {19    patch(oldChildren[index], newChildren[index], domNode.childNodes[index]);20  }21  for (let index = shared; index < newChildren.length; index += 1) {22    domNode.append(createDom(newChildren[index]));23  }24  for (let index = oldChildren.length - 1; index >= newChildren.length; index -= 1) {25    domNode.childNodes[index].remove();26  }27  return domNode;28}

The patch has six jobs. createDom is the mounting function from above, and updateProps updates attributes:

• Line 2: if both nodes are text, line 3 changes nodeValue (the text inside a Text node) only when the text differs.
• Line 7: if the tags differ, like h2 and p, it builds a new element and swaps it in.
• Line 13: if the tags match, it keeps the element and updates its attributes. Attributes that are gone get removed.
• Line 19: for each child that both trees have at the same position, it calls patch again.
• Line 22: it adds children the new tree has but the old one didn't.
• Line 25: it removes children the old tree had but the new one doesn't.

That is enough to learn the idea. A real framework does much more.

1function view(count, status) {Run2  return h("section", {},3    h("h2", {}, "Count: " + count),4    h("label", {}, "Draft ", h("input", { placeholder: "keeps value" })),5    h("p", { class: "status", "data-status": status }, status),6  );7}8 9const root = document.querySelector("#app");10let oldTree = view(0, "idle");11root.replaceChildren(createDom(oldTree));12const input = root.querySelector("input");13input.value = "still typing";14input.focus();15 16const nextTree = view(1, "saved");17patch(oldTree, nextTree, root.firstChild);18oldTree = nextTree;19console.log(root.querySelector("input") === input);20console.log(document.activeElement === input);21console.log(input.value);

The step-through counts the page changes: 2 text changes and 1 attribute change. Our renderer counts its own work: elements made, text changes, attribute changes, swaps, and children added or removed. A browser MutationObserver could count page changes too. Counting inside the renderer shows exactly what patch chose to do.

const before = ["Count: 0", "Saved"];
const after = ["Count: 1", "Saved"];
const changed = after.filter((value, index) => value !== before[index]).length;
console.log("changed values " + changed);

Line 3 compares the two lists position by position and keeps the values that differ. Only "Count: 0" and "Count: 1" differ. So line 4 prints changed values 1.

"Change only what differs" doesn't mean the view is skipped. This renderer still calls the view and builds a whole new description. It only skips page work for values that match, like "Saved". When building the description is itself slow, big frameworks track which values each part reads, or prepare the work ahead of time.

Reordered lists need keys

Our patch compares children by position. It assumes the first old child and the first new child are the same item. That is wrong when a list changes order. The code below shows the bug on purpose.

1const root = document.createElement("div");2const before = h("ul", {},3  h("li", { "data-id": "a" }, h("span", {}, "A"), h("input", {})),4  h("li", { "data-id": "b" }, h("span", {}, "B"), h("input", {})),5);6root.append(createDom(before));7root.querySelector("input").value = "typed for A";8 9const after = h("ul", {},10  h("li", { "data-id": "b" }, h("span", {}, "B"), h("input", {})),11  h("li", { "data-id": "a" }, h("span", {}, "A"), h("input", {})),12);13patch(before, after, root.firstChild);14const firstRow = root.querySelector("li");15console.log(firstRow.querySelector("span").textContent + ":" + firstRow.querySelector("input").value);

• Line 2 describes a list with row A, then row B. Each row has an input.
• Line 7 types typed for A into the first input, in row A.
• Line 9 describes the new order: B first, then A.
• Line 13 patches. The first row keeps its input. Only its letter and its data-id change, from A to B.
• Line 15 prints B:typed for A. Row B now shows the text typed for A.

The fix is a key: a fixed id for each item, like data-id. A patch that uses keys matches old and new rows by key, not by position:

• It moves each matching row to its new place.
• It builds rows only for new keys.
• It removes rows only for keys that are gone.

Real frameworks work hard on this. Forms and animations break when a row loses track of which item it belongs to.

The view makes new buttons on many renders. But the framework never adds a listener to those buttons. Instead, one listener sits on the root element, #app. This is event delegation: one listener on a parent handles events from everything inside it.

It works because clicks bubble. After you click a button, the click event travels up through each parent element, all the way to the root. There the listener does two checks:

• event.target.closest("[data-action]") finds the button. closest starts at the clicked element and walks up through its parents. It returns the first one that has a data-action attribute.
• root.contains(button) makes sure that button is inside the root.

The table shows each piece of the event code and what it is for. The last column names the lesson to review.

Delegation has limits. A child can call stopPropagation(), and then the click never reaches the root. And some events don't bubble at all, like focus. For focus, listen for focusin instead, or listen while the event travels down. The event delegation lesson explains both.

1const listeners = new Set();2function subscribe(listener) {3  listeners.add(listener);4  return () => listeners.delete(listener);5}6function emit() {7  for (const listener of listeners) listener();8}9const stop = subscribe(() => console.log("render"));10emit();11stop();12emit();13console.log("remaining " + listeners.size);

• Line 2 starts subscribe. Line 4 returns a function that removes the listener.
• Line 9 adds a listener and keeps that remove function in stop.
• Line 10 calls the listeners, so it prints render.
• Line 11 calls stop(). So line 12 prints nothing.
• Line 13 prints remaining 0.

A listener has an owner: the view that added it. So the mount function should return a cleanup function. When the view goes away, call cleanup first, then remove the page elements. The same rule fits listeners, timers, observers, sockets, and shared stores: remove them when the view that made them goes away.

The playground below runs the real tiny framework inside an empty element. Try these:

• Three writes at once adds 1 to the count twice and pushes one todo. All three happen before the microtask, so the render count goes up by only one.
• Replace the todo array puts a whole new array into state.todos. It renders too.
• Type, then add 1 types into the input, then adds 1 to the count. The input keeps its text and focus.

1const root = document.querySelector("#app");2root.addEventListener("click", (event) => {3  const button = event.target.closest("[data-action]");4  if (!button || !root.contains(button)) return;5 6  if (button.dataset.action === "increment") {7    state.count += 1;8  }9  if (button.dataset.action === "toggle") {10    const todo = state.todos.find((item) => item.id === Number(button.dataset.id));11    if (todo) todo.done = !todo.done;12  }13});

const app = mountTinyReactiveUi(document.querySelector("#app"), (snapshot) => {
  console.log(snapshot.renderCount + ":" + snapshot.count + ":" + snapshot.todos.join("|"));
});
app.burst();
queueMicrotask(() => {
  app.replaceTodos();
  queueMicrotask(() => app.destroy());
});

This is the loop from the app architecture lesson:

1. A click reaches the root listener.
2. The listener changes the state.
3. The Proxy asks for a render, and the scheduler queues one.
4. The view builds a new virtual tree.
5. patch updates the page and keeps the elements that match.

Each part has one job. The root listener takes in clicks. The view only describes the page. The state object is the one place the data lives.

What real frameworks add

Our framework is for learning. Real apps need more. Here is some of what it doesn't have:

• Components: small reusable pieces of page, each with its own state.
• Cleanup that runs by itself when a piece of page goes away.
• Lists matched by key.
• Hydration: taking over HTML that a server already sent.
• A way to show a fallback when part of the page throws an error.
• Warnings about accessibility problems.
• A compiler that prepares the page code before it reaches the browser.
• Developer tools for looking inside the app.

Real apps have forms, animations, data that arrives in pieces, and thousands of elements. Parts of them fail. These extra pieces help them keep working.

The table shows what each added piece does in a real framework.

Frameworks built on signals don't compare whole trees. Each signal remembers which part of the page read it, and only that part updates. Frameworks with a virtual tree are less exact, but their views are simple functions that are easy to combine. Both designs are fine when you know what each one costs.

Misconceptions

• "A Proxy makes every nested object reactive right away." Not in this design. A nested object gets its own Proxy the first time it is read.
• "Changing an array can't trigger a render." It can. push writes an index and length through the array's Proxy. Putting in a whole new array works too, through the state object's Proxy.
• "A virtual tree is a string of HTML." No. A virtual node is a plain object. The page is built from it with Text nodes and elements, so user text stays text.
• "Comparing trees always keeps each item with its own element." Not when it compares by position. A reordered list needs keys.
• "One listener on the root is always better." For one button that never changes, a listener on the button is fine. Delegation helps most with many buttons, or buttons that come and go.

The table compares three ways to update a page. Read each row from left to right.

Key takeaways

• A Proxy's set trap can ask for a render on every write. Reflect.set still does the normal write.
• queueMicrotask and a queued flag join many writes in one run of code into one render of the newest state.
• A virtual node is a plain object that describes an element. Build the page from it with elements and Text nodes, never by reading user text as HTML.
• A patch changes text, attributes, and children, and keeps every page element that still matches.
• Comparing children by position breaks when a list changes order. Real frameworks match items by key.
• One listener on the root handles clicks from new and rebuilt buttons, because clicks bubble up to it.
• Calculate derived values from one place in the state. Give every listener a way to stop.
• Use Text nodes or textContent for user text, and check links before you use them.

One-line summary: a reactive UI turns state changes into one render that builds a description of the page, then changes only the parts of the real page that differ.

Up next: XSS. There, the rule "show user text as text" becomes a full security habit.