Preview Frame

Embeds a live preview iframe and drives the hp-preview postMessage protocol: answers the frame’s ready handshake with a config payload fetched from data-uri, auto-saves watched forms on change, refreshes the preview after each save (its own, or a shell-driven save of a refresh-on form), accepts a theme payload via setTheme() that is retained and replayed after every ready handshake, and grows the frame to a content height the embed reports so the panel scrolls an overflowing page.

The frame loads the embed page from src, waits for it to post hp-preview:ready, fetches the JSON payload from data-uri and posts it back into the frame as hp-preview:config. The embed then reports hp-preview:rendered or hp-preview:error.

The example below embeds the demo embed page, which implements the embed side of the protocol. frame-origin must match the embed’s origin exactly — messages from any other origin are ignored — so the example sets it at runtime since the docs demo is same-origin.

<zn-preview-frame
  id="preview-frame-demo"
  src="/components/preview-frame-demo/"
  data-uri="/data/preview-frame-payload.json"
  watch="#preview-frame-demo-form"></zn-preview-frame>

<script>
  document.getElementById('preview-frame-demo').frameOrigin = location.origin;
</script>

The frame always fills the panel; zoom (0–1, default 1) zooms the previewed page out browser-style — e.g. zoom="0.4" renders the content at 40% size with correspondingly more of the page visible. min-height (default 480) sets the visible panel height in pixels.

Set fill to make the panel fill its container’s height instead — min-height then becomes a floor rather than the height, for hosts (like zn-theme-editor) whose layout already stretches the panel to match a taller sibling. zoom is ignored when fill is set, since its oversize maths needs a known pixel height to scale against, which fill deliberately doesn’t have.

device constrains and centres the preview to desktop (full width), tablet (768px) or mobile (390px), resizing the iframe itself so the embedded page’s media queries fire. setTheme({mode, values}) posts an hp-preview:theme message and replays it after each ready handshake, which is how zn-theme-editor drives a live preview.

The panel behind the preview is a dot grid, so the frame’s bounds stay visible instead of blending into the page — at tablet or mobile the dots fill the gutters either side of the narrowed iframe. Tune it with --zn-preview-frame-dot-spacing (default 20px) and --zn-preview-frame-dot-opacity (default 0.08). The iframe itself is given an opaque background, so the dots never show through the previewed page.

Set backdrop="panel" to swap the dot grid for a plain rgb(var(--zn-panel)) fill — used by zn-theme-editor’s standalone mode, where the frame is already inside its own bordered panel. backdrop="dots" is the default.

Interactivity

The preview is display-only: the iframe takes pointer-events: none, so clicks never reach the embedded page and the previewed form can’t be submitted or navigated away from inside the frame. The embed is cross-origin, so its own handlers can’t be cancelled from out here — blocking pointer input is the only way to stop them, and hover goes with it. Scrolling doesn’t: an overflowing page is scrolled by the panel instead, as below.

Set interactive when the embed is meant to be used rather than looked at. The frame then behaves as a viewport: it stays the panel’s own height and the embed scrolls itself, so there’s a single scrollbar and the embed’s 100vh, position: fixed and sticky content size to what’s actually on screen. The reported content height is ignored while interactive is set — it exists to make an inert frame’s overflow reachable, which an interactive one does for itself.

<zn-preview-frame
  id="preview-frame-interactive"
  src="/components/preview-frame-demo/"
  data-uri="/data/preview-frame-payload.json"
  watch="#preview-frame-interactive-none"
  interactive></zn-preview-frame>

<script>
  document.getElementById('preview-frame-interactive').frameOrigin = location.origin;
</script>

Overflowing Content

An inert page taller than the panel is scrolled by the panel, not inside the frame. The frame can’t do it itself: a cross-origin document can’t be scrolled from the host (contentWindow.scrollTo is blocked), and with pointer input off the wheel never reaches it anyway. So the frame is instead laid out at its full content height — nothing scrolls inside it — and the panel scrolls that. An interactive frame doesn’t need any of this and opts out of it: it keeps the panel’s height and the embed scrolls itself.

For the frame to be sized that way, the embed reports its height alongside hp-preview:rendered:

post({
  type: 'hp-preview:rendered',
  height: document.documentElement.scrollHeight
});

A page that grows after its first render — a revealed section, a lazy-loaded image — reports the new height on its own:

post({type: 'hp-preview:height', height: document.documentElement.scrollHeight});

Heights that aren’t a positive number are ignored, as is one reported while the error overlay is up. A height under the panel’s own is kept but changes nothing: the frame still fills the panel, so the backdrop never shows under a short page. The height is dropped whenever src changes, since the next page has its own.

The example below previews a long itemised page, so the panel scrolls. Scrolling works with the frame inert — clicking Pay still does nothing.

<zn-preview-frame
  id="preview-frame-tall"
  src="/components/preview-frame-demo/"
  data-uri="/data/preview-frame-payload-tall.json"
  watch="#preview-frame-tall-none"></zn-preview-frame>

<script>
  document.getElementById('preview-frame-tall').frameOrigin = location.origin;
</script>

Live Form Updates

In a real deployment, editing a watched form auto-saves it and the preview refreshes with the newly saved config. This docs site is static, so the example simulates the save: form changes are encoded into a data: payload URI and refresh() re-runs the fetch → hp-preview:config cycle — the same path a real save triggers.

<form id="preview-frame-live-form" class="preview-frame-live-form">
  <zn-input name="merchant" label="Merchant" value="Acme Donuts"></zn-input>
  <zn-input name="amount" label="Amount" value="£24.99"></zn-input>
  <zn-input name="buttonLabel" label="Button label" value="Pay £24.99"></zn-input>
  <label class="preview-frame-live-form__color">Accent
    <input type="color" name="accent" value="#6936f5">
  </label>
</form>

<zn-preview-frame
  id="preview-frame-live"
  src="/components/preview-frame-demo/"
  watch="#preview-frame-live-none"></zn-preview-frame>

<script>
  customElements.whenDefined('zn-preview-frame').then(() => {
    const frame = document.getElementById('preview-frame-live');
    const form = document.getElementById('preview-frame-live-form');
    frame.frameOrigin = location.origin;

    const update = () => {
      const payload = Object.fromEntries(new FormData(form));
      frame.dataUri = 'data:application/json,' + encodeURIComponent(JSON.stringify(payload));
      frame.refresh();
    };

    form.addEventListener('zn-input', update);
    form.addEventListener('input', update);
    update();
  });
</script>

<style>
  .preview-frame-live-form {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
    align-items: flex-end;
    margin-bottom: 16px;
  }

  .preview-frame-live-form zn-input {
    flex: 1;
    min-width: 140px;
  }

  .preview-frame-live-form__color {
    display: flex;
    flex-direction: column;
    gap: 4px;
    font-size: 0.875rem;
    font-weight: 500;
  }
</style>

Error Overlay

When the embed reports hp-preview:error (or fetching the payload fails), the message is shown in an overlay and zn-error is emitted. This example uses a payload that asks the demo embed to fail.

<zn-preview-frame
  id="preview-frame-demo-error"
  src="/components/preview-frame-demo/"
  data-uri="/data/preview-frame-payload-error.json"
  watch="#preview-frame-demo-error-form"></zn-preview-frame>

<script>
  document.getElementById('preview-frame-demo-error').frameOrigin = location.origin;
</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.132/dist/components/preview-frame/preview-frame.js"></script>

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.132/dist/components/preview-frame/preview-frame.js';

import '@kubex/zinc/dist/components/preview-frame/preview-frame.js';

Properties

Learn more about attributes and properties.

Events

Learn more about events.

Methods

Learn more about methods.

Custom Properties

Learn more about customizing CSS custom properties.

Parts

Learn more about customizing CSS parts.