Preview Guard — Stimeo UI

← All components

When you press back, Turbo shows the page it remembered for a moment before the fresh one arrives. In that moment a balance, an unread count or a timestamp is on screen with its old value. This hides such a value for exactly that moment. There are two ways: leave it unset and the value becomes invisible while keeping its space, so nothing shifts; give it wording and that wording takes its place, with your markup restored afterwards. While it is guarded, CSS can tell. Fetching the current value is ordinary rendering's job.

running

Balance: ¥123,456
Updated: 12:34:56

While Turbo briefly shows a cached snapshot on a back/forward visit, the balance becomes a placeholder and the timestamp is hidden — so no stale value flashes (the button simulates that ~1.5s window).

Keyboard

This component has no keyboard interactions of its own.

<%# Preview-guard demo: data-turbo-preview is a Turbo-internal attribute, so this catalog
    has no real preview to show. demo.js toggles it on <html> for ~1.5s to reproduce a
    preview window — exactly what Turbo does on a back/restore visit. The balance declares a
    placeholder, so it swaps to —; the timestamp declares none, so it goes invisible with its
    box kept. The library only watches the attribute and reflects data-preview-hidden. %>
<div class="preview-guard-demo">
  <button type="button" class="demo-trigger" data-preview-guard-demo-toggle>
    <%= t("components.preview_guard.demo.toggle") %>
  </button>

  <dl class="preview-guard-demo__list">
    <div class="preview-guard-demo__row">
      <dt><%= t("components.preview_guard.demo.balance_label") %></dt>
      <dd>
        <span
          class="preview-guard-demo__value"
          data-controller="stimeo--preview-guard"
          data-stimeo--preview-guard-placeholder-value="—"
        ><%= t("components.preview_guard.demo.balance") %></span>
      </dd>
    </div>
    <div class="preview-guard-demo__row">
      <dt><%= t("components.preview_guard.demo.updated_label") %></dt>
      <dd>
        <span
          class="preview-guard-demo__value"
          data-controller="stimeo--preview-guard"
        ><%= t("components.preview_guard.demo.updated") %></span>
      </dd>
    </div>
  </dl>

  <p class="preview-guard-demo__note"><%= t("components.preview_guard.demo.note") %></p>
</div>

/*
 * Presentation-only styles for the preview-guard demo. The library swaps the text
 * (placeholder mode) or sets visibility:hidden (hide mode) and reflects
 * data-preview-hidden; this CSS only lays out the rows and tints a guarded value so the
 * placeholder swap is easy to spot.
 */

.preview-guard-demo {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  max-width: 24rem;
}

.preview-guard-demo__list {
  margin: 0;
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

.preview-guard-demo__row {
  display: flex;
  justify-content: space-between;
  gap: 1rem;
  padding: 0.5rem 0.75rem;
  border: 1px solid var(--border);
  border-radius: 0.375rem;
}

.preview-guard-demo__row dt {
  color: var(--color-text-muted);
}

.preview-guard-demo__row dd {
  margin: 0;
  font-variant-numeric: tabular-nums;
}

.preview-guard-demo__value[data-preview-hidden] {
  color: var(--color-text-subtle);
}

.preview-guard-demo__note {
  margin: 0;
  color: var(--color-text-muted);
}

// Preview-guard demo (consumer-side JS).
//
// Turbo sets html[data-turbo-preview] itself while a cached preview is on screen. This
// catalog navigates with Turbo but opts its component pages out of previews, so the button
// toggles that attribute for ~1.5s to reproduce the preview window. Every preview-guard on
// the page reacts (just as they would during a real preview), guarding their volatile
// values until it clears.
document.querySelectorAll(".preview-guard-demo").forEach((root) => {
  const button = root.querySelector("[data-preview-guard-demo-toggle]");
  if (!button) return;
  // Idempotent: Turbo can re-run this inline module on navigation; wire each root once. The
  // marker is a property, not an attribute: Turbo copies attributes into its page snapshot,
  // so an attribute one comes back set on a restored page whose elements carry no listeners.
  if (root.demoWired) return;
  root.demoWired = true;

  button.addEventListener("click", () => {
    document.documentElement.setAttribute("data-turbo-preview", "");
    setTimeout(() => {
      document.documentElement.removeAttribute("data-turbo-preview");
    }, 1500);
  });
});

These demo styles use shared design tokens (light + dark). Copy the shared styles too, then toggle data-theme on your root element for dark mode.

The data-* attributes you add to your own HTML to wire this component. Put the data-controller below on a root element, then place its targets / values / actions inside that element.

On the root element data-controller="stimeo--preview-guard"

Values

Name	Description	Attribute
`placeholder`	Text that replaces the element's content while guarded. Empty (the default) hides the element with `visibility:hidden` instead, keeping its box.	`data-stimeo--preview-guard-placeholder-value`

Events

Name	Description	Event
`hide`	Fires when the element is guarded as a preview begins.	`stimeo--preview-guard:hide`
`show`	Fires when the element is restored as the preview clears.	`stimeo--preview-guard:show`

State hooks

The library only manages these ARIA/data attributes and custom properties. Your CSS reads them to render the look — selectors like [aria-selected], [aria-expanded], or var(--stimeo--…) hook into this state.

Hook	Target	Meaning
`data-preview-hidden`	Controller element	Present (true) while guarded during a preview.