Third-party widgets & interop.

Why these exist

Aktion components render declaratively: you describe the tree, the runtime reconciles the DOM, and it reuses + patches nodes on every re-render to preserve focus, scroll, and form state. That is exactly wrong for a widget that builds its own DOM — a chart canvas, a map’s tile layers, an editor’s document. If the reconciler touched those nodes it would corrupt or destroy the widget mid-session.

The interop primitives solve this in one move: the host element they create is marked data-rui-preserve, which tells the reconciler “this subtree is owned by imperative code — never reconcile its children or reset its form state.” Aktion keeps flowing its own attributes (a reactive sx / class) but otherwise leaves the live node alone. You get reactive data binding around a widget that fully owns the DOM inside.

Mount — managed imperative widgets

Mount({ setup, update?, cleanup?, props?, tag?, sx? }) is the managed host for any imperative widget. Aktion creates the host element; you fill it and react to prop changes through a clean three-phase lifecycle.

chart = Mount({
  tag: "div",                          // host element (default "div")
  sx: { h: "320px" },                  // layout the host like any component
  setup: (node, props) => {            // runs ONCE after the host attaches
    return new Chart(node, props.config)  //   → return the instance handle
  },
  update: (instance, props) => {       // runs when `props` change (shallow-compared)
    instance.data = props.data
    instance.update()
  },
  cleanup: (instance) => instance.destroy(),  // runs on unmount
  props: { config: $cfg, data: $series }      // reactive bag handed to setup/update
})

The lifecycle contract

• props is the reactive boundary. Bind $state into props and update fires whenever any value changes — that is how the outside world drives the widget. Reading state inside setup / update is fine too.
• The host is never rebuilt. Because the host is preserved, re-renders never re-run setup or recreate the element — the widget instance lives for the whole session.
• Shallow compare. { data: $series } counts as changed only when $series is a new reference. Replace arrays/objects immutably (e.g. $series = [...]) to trigger an update.
• tag picks the host element ("div", "canvas", "section", …). Defaults to "div".

Live: a self-contained canvas

No external library needed — setup grabs the canvas 2D context and draws. This is the whole pattern in miniature: Aktion owns the <canvas>, your code owns the pixels.

$app(Column([
  Text("Drawn by an imperative Mount:", { sx: { weight: "600" } }),
  Mount({
    tag: "canvas",
    sx: { w: "100%", h: "140px", radius: "md" },
    setup: (node) => {
      node.width = 600; node.height = 280
      ctx = node.getContext("2d")
      ctx.fillStyle = "#6366f1"
      ctx.fillRect(20, 20, 200, 90)
      ctx.fillStyle = "#22c55e"
      ctx.beginPath()
      ctx.arc(360, 120, 70, 0, Math.PI * 2)
      ctx.fill()
      return ctx
    }
  })
]))

Full example: Chart.js with reactive data

Load the library with $script, gate the Mount on it being ready, then push reactive series in through props:

$chartjs = $script({ src: "https://cdn.jsdelivr.net/npm/chart.js", global: "Chart" })
$series  = [12, 19, 7, 15]

function SalesChart() {
  if (!$chartjs.ready) {
    return Skeleton({ sx: { h: "320px" } })   // graceful loading state
  }
  return Mount({
    sx: { h: "320px" },
    setup: (node, props) => new $chartjs.value(node, {
      type: "bar",
      data: { labels: ["Q1","Q2","Q3","Q4"], datasets: [{ data: props.series }] }
    }),
    update: (chart, props) => {
      chart.data.datasets[0].data = props.series
      chart.update()
    },
    cleanup: (chart) => chart.destroy(),
    props: { series: $series }
  })
}

$app(Column([
  SalesChart(),
  Button("Shuffle", { onClick: () => $series = $series.map(() => Math.round(Math.random() * 20)) })
]))

WebComponent — native custom elements

Many third-party widgets already ship as custom elements (<stripe-pricing-table>, <model-viewer>, a design-system element). WebComponent(tag, { attributes?, properties?, on?, children? }) renders and hydrates one with reactive attributes, rich JS properties, and event hooks.

widget = WebComponent("stripe-pricing-table", {
  attributes: {                         // reactive — re-applied on $state change
    "pricing-table-id": $id,
    "publishable-key":  $pk
  },
  on: {                                 // listeners stay current across renders
    "checkout": e => route.navigate("/thanks")
  }
})

Use attributes for simple string-ish values and properties when the element exposes a rich property API:

viewer = WebComponent("model-viewer", {
  attributes: { src: $modelUrl, "camera-controls": true, ar: true },
  properties: { cameraOrbit: $orbit },   // a rich, non-string property
  on: { "load": () => $loaded = true }
})

$script — load an external SDK once

$script({ src, global? }) loads an external UMD/ESM script (or stylesheet) exactly once per src across the whole app, and returns a reactive bag you gate your UI on.

$stripe = $script({ src: "https://js.stripe.com/v3/", global: "Stripe" })
// → { ready, loading, error, value }   (value = window.Stripe once loaded)

The canonical pattern is “don’t render the widget until its SDK exists”:

$maps = $script({ src: "https://maps.example.com/sdk.js", global: "MapSDK" })

function MapView() {
  if ($maps.error)  return Alert("Map failed to load", { variant: "danger" })
  if (!$maps.ready) return Spinner()
  return Mount({
    sx: { h: "400px" },
    setup: (node) => new $maps.value.Map(node, { center: [0, 0], zoom: 2 }),
    cleanup: (map) => map.remove()
  })
}

On the server (renderToString) there is no DOM to inject into, so the bag stays { ready: false } and your UI falls back to the loading branch — exactly what you want for an SSR placeholder that hydrates on the client.

$dom — managed observers

Migrating resize / intersection / mutation logic usually means hand-rolling an observer plus its teardown in an $effect. The $dom namespace does the bookkeeping: every observer it creates is auto-disposed on re-plan / unmount, and each method returns a disposer so you can stop early.

Pair these with a node reference from OnMount or a Mount host:

$w = 0
$app(OnMount(
  Box([ Text(`Container width: ${$w}px`, { sx: { weight: "600" } }) ], { sx: { p: "20px" } }),
  { onMount: (node) => $dom.onResize(node, ({ width }) => $w = Math.round(width)) }
))

// Lazy-load an image / fire analytics when a section scrolls into view:
$app(OnMount(Box([ Text("Reveal me") ]), {
  onMount: (node) => $dom.onIntersect(node, (entry) => {
    if (entry.isIntersecting) $seen = true
  }, { threshold: 0.25 })
}))

// One-shot measurement (no observer):
size = $dom.measure(node)   // → { rect: {width,height,top,left,…}, scroll, viewport }

How preservation works (and SSR)

Every interop host carries data-rui-preserve. During reconciliation Aktion treats such a node as a black box: it never reconciles its children or resets form state, but it does push its own attribute changes additively (so a reactive sx, class, or data-* still flows) and keeps event handlers current. That is what lets a chart keep its canvas while you restyle its wrapper.

Because the widget’s DOM is built imperatively on the client, interop hosts render as an empty placeholder during renderToString and come alive on hydration. Combine that with a !ready loading branch and your SSR output is a clean skeleton that fills in client-side — see Production & deployment.

Recipes

Monaco editor with two-way binding

$monaco = $script({ src: "https://cdn.example.com/monaco/loader.js", global: "monaco" })
$code   = "function hi() {}"

function Editor() {
  if (!$monaco.ready) return Skeleton({ sx: { h: "300px" } })
  return Mount({
    sx: { h: "300px", border: true, radius: "md" },
    setup: (node, props) => {
      ed = $monaco.value.editor.create(node, { value: props.value, language: "javascript" })
      ed.onDidChangeModelContent(() => $code = ed.getValue())
      return ed
    },
    update: (ed, props) => { if (props.value !== ed.getValue()) ed.setValue(props.value) },
    cleanup: (ed) => ed.dispose(),
    props: { value: $code }
  })
}

Stripe payment element

$stripe = $script({ src: "https://js.stripe.com/v3/", global: "Stripe" })

function Checkout() {
  if (!$stripe.ready) return Spinner()
  return Mount({
    sx: { minH: "60px" },
    setup: (node, props) => {
      stripe = $stripe.value(props.pk)
      elements = stripe.elements({ clientSecret: props.secret })
      card = elements.create("payment")
      card.mount(node)
      return { stripe, elements, card }
    },
    cleanup: (inst) => inst.card.destroy(),
    props: { pk: $publishableKey, secret: $clientSecret }
  })
}

Mount vs. WebComponent vs. OnMount

Next