How do you wrap a third-party imperative widget that builds and mutates its own host nodes inside a declaratively rendered component?

A mature imperative widget — a charting engine, a map, an editor, a video player — owns its own host nodes. It creates them, mutates them on its own schedule, and expects nobody else to touch them. A declarative framework also creates and mutates host nodes, and also expects nobody else to touch them. Wrapping one in the other is therefore not an API question but a **boundary** question: exactly which nodes does each side own? ## Draw the boundary first Your component renders **one container element and nothing inside it**. Everything below that node is the widget's territory; everything above is the framework's. Two rules follow immediately: - **Never render framework children into the container.** If the description says the container has children, reconciliation will assert them, deleting or reordering nodes the widget created. The symptoms are ugly and intermittent: content vanishing after an unrelated update, duplicated internals, event handlers bound to nodes that no longer exist. - **Never let the widget mutate nodes above the container.** A widget that appends to the surrounding layout puts its output where the framework believes it owns the children. You also want that container element to be **stable in the tree** so the framework has no reason to replace it. If the reconciler decides to discard that node and build a new one, the widget is left holding a node that is no longer on screen — the decision about when a node is kept or replaced is its own subject, but the wrapper's job is not to invite it. ## The phases of a wrapper 1. **Describe** — output the container. No widget calls here; the node does not exist yet, and the description step must be free of side effects so it can be run again. 2. **After commit** — the container node exists. Construct the widget onto it, pass the initial options derived from your inputs, register its callbacks, and keep the instance in a per-instance slot outside the reactive system. 3. **On update** — compare the inputs that matter and translate each change into the widget's own update call. This is the step people skip, and rebuilding instead is what makes wrapped widgets feel slow and lose their place. 4. **On teardown** — call the widget's dispose path so its listeners, timers, observers and animation loops stop. What that contract owes in general is a lifecycle subject of its own; here the point is that the widget, not the framework, knows what it attached. ## Update, do not rebuild | Input change | Right response | Symptom of getting it wrong | | --- | --- | --- | | A value the widget can set live | call its setter or update method | rebuild flashes and loses scroll or selection | | A whole dataset | hand over the new data through its data API | full re-render per keystroke upstream | | A construction-only option | dispose, rebuild, and say so in the wrapper's docs | change silently ignored | | A callback identity that changed | keep your own stable adapter and call through it | listener churn on every update | The adapter trick in the last row is worth naming: register **one** callback with the widget that calls whatever your current handler is, read from the per-instance slot. Then an upstream handler that is re-created on every update does not cause a register/unregister cycle inside the widget. ## Where there is no host at all If your application renders output somewhere with no host objects — a server producing markup, or a test environment without a real host tree — the widget cannot be constructed, because it has nothing to attach to. The wrapper's answer is to render the container and nothing else, and to construct only in the environment that has a host. That is also why wrapped widgets are the components that force a real host in tests: the interesting behaviour lives entirely in the phase a description-only test never reaches. ## Two more traps - **Duplicated state.** Copying the widget's internal state into your component state so the template can display it creates two truths that drift. Read what you need at the moment you need it, or have the widget's callback feed your state as the single writer — not both. - **Late callbacks.** Async widget work can call back after your component is gone. Guard on the per-instance slot being empty and ignore the callback, or you will be commanding a torn-down component — and that is also how a disposed widget keeps everything alive.