Host Access & Portals

A component framework's whole deal is that you describe the output you want and it creates, updates and removes the real host objects on your behalf — nodes in a browser document, views in a native view tree. A **host-node reference** is the sanctioned hole in that deal: a small container you attach to a rendered element, which the framework fills with the actual host object it created for that element. ## What the reference actually is Three properties explain almost every question asked about it. - It is a **live slot, not a value you computed.** The framework writes the node into it when that node is attached and clears it when the element leaves the tree. Nothing about it is a snapshot. - It is tied to **one element of one live instance.** Two instances of the same component each get their own slot, and moving the attachment to a different element repoints the slot. - In most runtimes it is **outside the reactive system**: writing to it schedules no render, and reading it in a computation does not make that computation re-run when the node changes. That is deliberate — it is an imperative handle onto the host, not state. It is also the narrowest escape hatch available, and that is the point: everything else stays declarative, and one clearly-marked line reaches the host. ## Why it is empty while you are describing output Rendering and applying are separate steps. The component runs to produce a description; the framework then creates, updates or removes host objects to match it. During the first step, the node for a brand-new element simply does not exist yet, so the slot is empty. On a later update the slot may hold the *previous* node with the previous geometry — which is worse than empty, because a stale number looks plausible and ships as a bug. | When you read the slot | What you get | Sound uses | | --- | --- | --- | | While producing the description | empty on first render; stale afterwards | none | | In post-commit work | the node exactly as just committed | measure, focus, command, hand over | | In an event handler | the currently attached node | command, read geometry | | After the element is removed | cleared in most runtimes | none | The invariant worth memorising is not a phase name: **never read the node in the same pass that decides what the node should be.** (Which phases exist, and exactly when measurement is safe, is a separate subject in its own right.) ## What references are legitimately for - Moving focus to something that has just appeared, or restoring it afterwards. - Scrolling a container or bringing a row into view. - Reading rendered geometry that only the host knows — a measured size or position you cannot derive from your own data. - Driving host surfaces with no declarative equivalent: media playback, a drawing surface, text selection and caret position. - Handing a node to an imperative third-party widget so it has somewhere to live. Notice what they have in common: each is a **command whose result is not renderable output**. That is the test for whether a reference is the right tool. ## The ownership line The framework owns the interior of the elements it renders. A reference lets you talk to a node; it does not transfer ownership of that node's content. 1. **Command or read** through the reference — that is the supported use. 2. If the thing you want to write is something the user sees, it belongs in **state or an input**, so the next render produces it. Text you poke into a rendered node is overwritten the next time reconciliation touches it. 3. **Never let the slot decide render output.** A render that reads the node and outputs something different is a loop waiting to happen: describe, commit, read, describe differently. A related trap is visible flicker: if you measure after commit and then write something that changes layout, the user can see the intermediate frame. The fix is to do the measure-and-adjust in whatever pre-paint step the runtime offers rather than in ordinary post-commit work. ## How runtimes differ Frameworks expose this in different shapes. Some give you an object with a single slot; some let you pass a function the framework calls with the node when it attaches and with nothing when it detaches; a compile-time runtime may bind a plain local variable for you. The *timing* also differs by reactivity model: a runtime that re-runs component functions and diffs a description fills the slot in a distinct later step, while a fine-grained runtime that creates nodes as it evaluates may fill it almost immediately, so "after the node exists" arrives earlier. What survives every model is the rule above — the description step is never the place to read the node.