Skip to content
kitn AI/UI

Remote

kai-remote

Mount a card from an external provider in a sandboxed cross-origin iframe — it speaks the same CardEnvelope / CardEvent contract as every built-in card, so your routing policy and event listeners work without change.

  • Shadow DOM
  • Cross-origin iframe
  • Auto-sizes from card height
  • Theme + locale push
  • Origin-validated mount

When to use

Section titled “When to use”

Reach for <kai-remote> when a card needs to run code you cannot (or choose not to) bundle into the host app — a third-party widget, a sandboxed partner form, or an internal micro-frontend with its own release cycle. The element handles the iframe lifecycle, height negotiation, theme push, and event routing; your app only supplies a CardEnvelope and listens for kai-card events.

Usage

Section titled “Usage”

Point the element at your provider and hand it the envelope:

<kai-remote
  provider-origin="https://cards.provider.example"
  src="https://cards.provider.example/card"
></kai-remote>


<script type="module">
  import '@kitn.ai/ui/elements';
  const el = document.querySelector('kai-remote');


  el.envelope = {
    type: 'form',
    id: 'remote-form-1',
    title: 'Quick question',
    data: { /* … your card data … */ },
  };


  el.addEventListener('kai-card', (e) => {
    if (e.detail.kind === 'submit') console.log('submitted', e.detail.data);
    if (e.detail.kind === 'action') console.log('action', e.detail.action);
  });
</script>
  • src — URL of the card page inside the provider. Plain HTML attribute.
  • provider-origin — exact HTTPS origin of the provider (e.g. https://cards.provider.example). http://localhost:PORT and http://127.0.0.1:PORT are accepted for local dev. Wildcards and comma-lists are rejected immediately with an inline error.
  • envelope — the CardEnvelope object. Assign it as a property (el.envelope = { type, id, data, … }), not an HTML attribute.
  • policy — an optional CardPolicy for programmatic event routing (same shape <kai-cards> uses), also set as a property. Omit it and all events still surface as bubbling kai-card CustomEvents.

Props

Section titled “Props”
PropertyTypeDefaultNotes
src string — The remote card URL. Attribute: `src`.
providerOrigin string — Exact provider origin (https: or http://localhost for dev). Attribute: `provider-origin`.
envelope Record<string, unknown> — The card envelope to render. JS property only.
policy Record<string, unknown> — Optional routing policy. JS property only.
Need a hand? Report a bug Ask for help