> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iris Reveal

> A circle clip-path opens from an authored origin revealing state B over state A in one confident pass, then holds on B. Classic register dims and desaturates the before state so the after state lands in full color; a thin accent rim rides the iris edge. Callers fill the named before/after slot panels; token-styled defaults render when a slot is left empty.

export const InstallCommand = ({command}) => {
  const [copied, setCopied] = React.useState(false);
  const copy = async () => {
    try {
      if (navigator.clipboard && window.isSecureContext) {
        await navigator.clipboard.writeText(command);
      } else {
        const previous = document.activeElement;
        const scratch = document.createElement("textarea");
        scratch.value = command;
        scratch.setAttribute("readonly", "");
        scratch.style.position = "fixed";
        scratch.style.opacity = "0";
        document.body.appendChild(scratch);
        scratch.select();
        document.execCommand("copy");
        document.body.removeChild(scratch);
        previous?.focus?.();
      }
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch {}
  };
  return <div className="hf-install-command not-prose my-4 flex items-stretch overflow-hidden rounded-xl border border-zinc-200 bg-zinc-50 dark:border-zinc-800 dark:bg-zinc-900">
      <code className="flex-1 overflow-x-auto whitespace-nowrap border-r border-zinc-200 px-4 py-3 font-mono text-sm text-zinc-800 dark:border-zinc-800 dark:text-zinc-100">
        {command}
      </code>
      <button type="button" onClick={copy} data-copied={copied ? "true" : "false"} aria-label={`Copy ${command} to the clipboard`} className="hf-install-copy">
        <svg className="hf-install-copy-clipboard" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M14.25 5.25H7.25C6.14543 5.25 5.25 6.14543 5.25 7.25V14.25C5.25 15.3546 6.14543 16.25 7.25 16.25H14.25C15.3546 16.25 16.25 15.3546 16.25 14.25V7.25C16.25 6.14543 15.3546 5.25 14.25 5.25Z" />
          <path d="M2.80103 11.998L1.77203 5.07397C1.61003 3.98097 2.36403 2.96397 3.45603 2.80197L10.38 1.77297C11.313 1.63397 12.19 2.16297 12.528 3.00097" />
        </svg>
        <svg className="hf-install-copy-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M2.75 9.5L6.5 13.25L15.25 4.5" />
        </svg>
      </button>
      <span className="hf-install-copy-status" role="status" aria-live="polite">
        {copied ? "Copied" : ""}
      </span>
    </div>;
};

<iframe className="w-full aspect-video rounded-xl border-0 bg-zinc-100 dark:bg-zinc-800" title="iris-reveal preview" loading="lazy" srcDoc={`<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;height:100%;overflow:hidden;background:transparent}hyperframes-player{display:block;width:100%;height:100%}</style><script src="https://cdn.jsdelivr.net/npm/@hyperframes/player@0.7/dist/hyperframes-player.global.js"><\/script></head><body><script>fetch("/public/catalog/components/iris-reveal.json").then(function(r){return r.json()}).then(function(d){var p=document.createElement("hyperframes-player");p.setAttribute("srcdoc",d.html);p.setAttribute("controls","");p.setAttribute("autoplay","");p.setAttribute("loop","");p.setAttribute("muted","");p.setAttribute("poster","https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/iris-reveal.png");document.body.appendChild(p)});<\/script></body></html>`} />

## Install

<InstallCommand command="npx hyperframes add iris-reveal" />

That writes one file: `compositions/components/iris-reveal.html`.

## Paste it into your composition

Open `compositions/components/iris-reveal.html` and copy what is inside into your own composition.

A component has no size or duration of its own. It takes both from the composition
you paste it into.

## Variables

Every one of these has a default, so the piece works untouched. Set the ones you
want to change on the element:

| Variable   | Default | Accepts                   | What it does                                                                                                     |
| ---------- | ------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `iris_x`   | `50`    | 0% to 100%, step 1%       | Horizontal iris origin as a percent of the frame width.                                                          |
| `iris_y`   | `50`    | 0% to 100%, step 1%       | Vertical iris origin as a percent of the frame height.                                                           |
| `open_at`  | `0.35`  | 0s to 8s, step 0.05s      | Seconds after mount start when the iris begins opening.                                                          |
| `register` | `color` | `color`, `plain`          | Color dims and desaturates the before state so the after state lands in full color. Plain leaves both untouched. |
| `accent`   | `green` | `green`, `blue`, `violet` | Iris rim ring and default after art tint.                                                                        |
| `exit`     | `none`  | `none`, `fade`, `up`      | Outgoing transition. None holds the final revealed frame.                                                        |

Set them with `data-variable-values` on the element that mounts it. These are the
defaults, so this behaves exactly like the preview above until you change one:

```html wrap theme={null}
<div
  data-composition-id="iris-reveal"
  data-composition-src="compositions/components/iris-reveal.html"
  data-variable-values='{"iris_x":50,"iris_y":50,"open_at":0.35,"register":"color","accent":"green","exit":"none"}'
></div>
```

## Source

<Accordion title={`iris-reveal.html`}>
  ```html theme={null}
  <!doctype html>
  <!--
    iris-reveal: HyperFrames video primitive (transitions / bridge)

    Concept: a circle clip-path opens from an authored origin (iris_x/iris_y
    percent) revealing state B over state A. Classic register: A grayscale and
    dimmed, B full color. One confident pass, then a still hold on B. Two
    full-bleed content slots (the before-after-wipe convention) with
    token-styled defaults; callers supply the two states, the primitive
    supplies the iris.

    Wave K, unit K2. Clip-path only (no dashes, no masks); both endpoints of
    the opening tween are authored (fromTo via a seeded proxy), so seeks are
    deterministic in both directions.

    Slots (see README.md for a worked example):
      - [data-slot="before"]: state A, the base layer. Replace the children of
        this element in your installed copy. Default: a muted token wireframe.
      - [data-slot="after"]:  state B, revealed by the iris. Same mechanism.
        Default: a brand-tinted version of the wireframe.
      Direct img/video children of a slot are sized to cover the panel.

    Variables (declared in data-composition-variables below):
      - iris_x (number, default 50, 0 to 100%): iris origin, percent of width.
      - iris_y (number, default 50, 0 to 100%): iris origin, percent of height.
      - open_at (number, seconds, default 0.35): when the iris starts opening,
        relative to mount start. Clamped so the pass completes inside IN.
      - register (color | plain, default color): color dims and desaturates
        state A so B lands in full color; plain leaves both states untouched.
      - accent (green | blue | violet, default green): iris rim ring and the
        default after art tint. green maps to --brand, blue to --accent,
        violet to --accent-2.
      - exit (none | fade | up, default none): outgoing transition. none holds
        the final frame (frame roots own transitions; holds end films).

    The iris rim is a thin accent circle (SVG stroke, fixed width) that rides
    the exact same radius proxy as the clip-path, so rim and clip edge are
    locked on every frame. It fades in as the pass starts and dissolves just
    before the iris clears the frame corners.

    Envelope (fixed IN/OUT, elastic HOLD only, never gsap.timeScale()):
      IN       = open_at + 1.10s iris pass (stage settles during the first 0.32s)
      HOLD     = elastic = max(0, D - (IN + OUT)); deliberately still on B
      OUT      = 0.50s when exit is fade or up, 0 when exit is none
      If D < IN + OUT, IN and OUT scale down together so IN + OUT == D.

    Sync point: iris-open land at open_at + 1.10s inside IN (1.45s at
    defaults). It never moves into elastic HOLD.

    Sound cue: dispatches a bubbling `hf:sfx` CustomEvent with id
    "iris-land-soft" at iris land. This primitive never plays audio.

    Determinism: the full radius and the iris center are measured in px once
    at mount (the K-wave law for cq-unit transform traps); the radius proxy is
    the single owner of clip and rim progress, re-written on every seek via
    onUpdate. Quiet register by default (L2); no percussive variants.

    Mount contract: MOUNTABLE SUB-COMPOSITION. The runtime clones only
    <template> contents; #root fills the host box (inset:0, container-type:
    size), has no data-width/data-height, and registers one paused timeline
    under the literal "iris-reveal" key (mount flattening strips
    data-composition-id from the live root). Variables come from
    window.__hyperframes.getVariables().
  -->
  <html
    lang="en"
    data-composition-id="iris-reveal"
    data-composition-duration="3.5"
    data-composition-variables='[
      { "id": "iris_x", "type": "number", "role": "layout", "label": "Iris origin X", "description": "Horizontal iris origin as a percent of the frame width.", "default": 50, "min": 0, "max": 100, "step": 1, "unit": "%" },
      { "id": "iris_y", "type": "number", "role": "layout", "label": "Iris origin Y", "description": "Vertical iris origin as a percent of the frame height.", "default": 50, "min": 0, "max": 100, "step": 1, "unit": "%" },
      { "id": "open_at", "type": "number", "role": "timing", "label": "Open start", "description": "Seconds after mount start when the iris begins opening.", "default": 0.35, "min": 0, "max": 8, "step": 0.05, "unit": "s" },
      { "id": "register", "type": "enum", "role": "style", "label": "Register", "description": "Color dims and desaturates the before state so the after state lands in full color. Plain leaves both untouched.", "default": "color", "options": [{ "value": "color", "label": "Color" }, { "value": "plain", "label": "Plain" }] },
      { "id": "accent", "type": "enum", "role": "style", "label": "Accent", "description": "Iris rim ring and default after art tint.", "default": "green", "options": [{ "value": "green", "label": "Green" }, { "value": "blue", "label": "Blue" }, { "value": "violet", "label": "Violet" }] },
      { "id": "exit", "type": "enum", "role": "timing", "label": "Exit", "description": "Outgoing transition. None holds the final revealed frame.", "default": "none", "options": [{ "value": "none", "label": "None" }, { "value": "fade", "label": "Fade" }, { "value": "up", "label": "Up" }] }
    ]'
  >
    <head>
      <meta charset="UTF-8" />
      <title>Iris Reveal</title>
    </head>
    <body>
      <template>
        <div id="root" data-composition-id="iris-reveal" data-duration="3.5" data-fps="30">
          <style>
            *,
            *::before,
            *::after {
              box-sizing: border-box;
            }

            /* Root fills the host-owned box. Internal measurements use cqw/cqh
               and every painted color comes from a contract token. */
            #root {
              position: absolute;
              inset: 0;
              container-type: size;
              isolation: isolate;
              overflow: hidden;
              background: var(--bg, #07111f);
              color: var(--fg, #f8fafc);
              font-family: var(--font-body, Inter, system-ui, sans-serif);
            }

            .ir-clip,
            .ir-stage,
            .ir-panel,
            .ir-slot,
            .ir-rim {
              position: absolute;
              inset: 0;
              width: 100%;
              height: 100%;
            }

            .ir-clip {
              overflow: hidden;
            }

            .ir-stage {
              opacity: 0;
            }

            .ir-panel {
              overflow: hidden;
            }

            /* The after layer is revealed by one circle clip-path. --ir-r (px)
               is written by the radius proxy, the single owner of iris
               progress; --ir-cx/--ir-cy are set once at mount. */
            .ir-after {
              z-index: 2;
              clip-path: circle(calc(var(--ir-r, 0) * 1px) at var(--ir-cx, 50%) var(--ir-cy, 50%));
            }

            /* Classic register: state A reads dimmed and desaturated so state B
               lands in full color. Static CSS, never tweened. */
            #root[data-register="color"] .ir-before .ir-slot {
              filter: grayscale(1) brightness(0.76);
            }

            /* Caller-supplied media covers its panel edge to edge. */
            .ir-slot > img,
            .ir-slot > video {
              position: absolute;
              inset: 0;
              width: 100%;
              height: 100%;
              object-fit: cover;
            }

            /* The rim ring rides the same radius proxy as the clip edge. Fixed
               stroke width in px (set at mount), fill none, no dashes. */
            .ir-rim {
              z-index: 3;
              overflow: visible;
              pointer-events: none;
            }

            .ir-rim circle {
              fill: none;
              stroke: var(--ir-accent, #22c55e);
            }

            /* Token-styled default slot content: a wireframe card that reads
               muted on the before layer and brand-tinted on the after layer.
               Callers replacing slot children never see any of this. */
            .ir-default {
              position: absolute;
              inset: 0;
              display: grid;
              place-items: center;
            }

            .ir-before .ir-default {
              background:
                linear-gradient(
                    color-mix(in srgb, var(--border, #334155) 34%, transparent) 0.12cqw,
                    transparent 0.12cqw
                  )
                  0 0 / 5cqw 5cqw,
                linear-gradient(
                    90deg,
                    color-mix(in srgb, var(--border, #334155) 34%, transparent) 0.12cqw,
                    transparent 0.12cqw
                  )
                  0 0 / 5cqw 5cqw,
                var(--surface, #172033);
            }

            .ir-after .ir-default {
              background: linear-gradient(
                135deg,
                color-mix(in srgb, var(--brand, #22c55e) 32%, var(--surface, #172033)) 0%,
                var(--surface, #172033) 58%,
                color-mix(in srgb, var(--ir-accent, #22c55e) 22%, var(--surface, #172033)) 100%
              );
            }

            .ir-card {
              width: 56cqw;
              height: 56cqh;
              padding: var(--space-3, 4cqh) var(--space-3, 4cqw);
              border: 0.16cqw solid var(--border, #334155);
              border-radius: var(--radius, 2.4cqmin);
              background: color-mix(in srgb, var(--surface, #172033) 88%, var(--bg, #07111f));
              box-shadow: 0 2cqh 5cqw color-mix(in srgb, var(--bg, #07111f) 45%, transparent);
            }

            .ir-after .ir-card {
              border-color: color-mix(in srgb, var(--ir-accent, #22c55e) 52%, var(--border, #334155));
              background: color-mix(in srgb, var(--surface, #172033) 86%, var(--brand, #22c55e));
            }

            .ir-bar {
              width: 34%;
              height: 4.4cqh;
              margin-bottom: var(--space-3, 4cqh);
              border-radius: 1.2cqh;
              background: var(--muted, #94a3b8);
              opacity: 0.5;
            }

            .ir-after .ir-bar {
              background: var(--ir-accent, #22c55e);
              opacity: 0.92;
            }

            .ir-line {
              height: 2.4cqh;
              margin-bottom: var(--space-2, 2.6cqh);
              border-radius: 1.2cqh;
              background: var(--muted, #94a3b8);
              opacity: 0.4;
            }

            .ir-line:nth-of-type(2) {
              width: 92%;
            }

            .ir-line:nth-of-type(3) {
              width: 68%;
            }

            .ir-line:nth-of-type(4) {
              width: 44%;
            }

            .ir-after .ir-line {
              background: color-mix(in srgb, var(--brand, #22c55e) 70%, var(--fg, #f8fafc));
              opacity: 0.75;
            }
          </style>

          <div
            id="iris-reveal-clip"
            class="ir-clip clip"
            data-start="0"
            data-duration="3.5"
            data-track-index="0"
          >
            <div class="ir-stage">
              <section class="ir-panel ir-before" aria-label="Before panel">
                <div class="ir-slot" data-slot="before">
                  <!-- SLOT "before": replace the children of this element with
                       your own content (img, video, or HTML). -->
                  <div class="ir-default" aria-hidden="true">
                    <div class="ir-card">
                      <div class="ir-bar"></div>
                      <div class="ir-line"></div>
                      <div class="ir-line"></div>
                      <div class="ir-line"></div>
                    </div>
                  </div>
                </div>
              </section>

              <section class="ir-panel ir-after" aria-label="After panel">
                <div class="ir-slot" data-slot="after">
                  <!-- SLOT "after": replace the children of this element with
                       your own content (img, video, or HTML). -->
                  <div class="ir-default" aria-hidden="true">
                    <div class="ir-card">
                      <div class="ir-bar"></div>
                      <div class="ir-line"></div>
                      <div class="ir-line"></div>
                      <div class="ir-line"></div>
                    </div>
                  </div>
                </div>
              </section>

              <svg class="ir-rim" aria-hidden="true">
                <circle class="ir-rim-circle" cx="0" cy="0" r="0"></circle>
              </svg>
            </div>
          </div>

          <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
          <script>
            (function () {
              "use strict";

              var root = document.getElementById("root");
              // Literal id: mount flattening strips data-composition-id from the
              // live root before this timeline registers.
              var compositionId = "iris-reveal";
              var stage = root.querySelector(".ir-stage");
              var after = root.querySelector(".ir-after");
              var rim = root.querySelector(".ir-rim");
              var rimCircle = root.querySelector(".ir-rim-circle");

              var vars =
                window.__hyperframes && window.__hyperframes.getVariables
                  ? window.__hyperframes.getVariables()
                  : {};

              function clampNumber(raw, fallback, min, max) {
                var value = raw == null ? fallback : Number(raw);
                if (!Number.isFinite(value)) return fallback;
                return Math.max(min, Math.min(max, value));
              }

              // INVARIANT: iris origin always clamps into the declared 0-100 range.
              var irisX = clampNumber(vars.iris_x, 50, 0, 100);
              var irisY = clampNumber(vars.iris_y, 50, 0, 100);
              var openAt = clampNumber(vars.open_at, 0.35, 0, 8);
              var register = vars.register === "plain" ? "plain" : "color";
              // Each enum choice routes to a DIFFERENT contract token so the
              // variable stays meaningful under a theme.
              var accentColors = {
                green: "var(--brand, #22c55e)",
                blue: "var(--accent, #38bdf8)",
                violet: "var(--accent-2, #c5a3ff)",
              };
              var accent = Object.prototype.hasOwnProperty.call(accentColors, vars.accent)
                ? vars.accent
                : "green";
              // The bundler mirrors composition variables as scoped CSS custom
              // props, so this unit's own accent variable can shadow the
              // contract --accent token inside the subtree ("blue" is a valid
              // CSS color and would render pure blue). When the shadow is
              // present, fall back to the literal contract value.
              var computedAccent = getComputedStyle(root).getPropertyValue("--accent").trim();
              if (
                computedAccent === "green" ||
                computedAccent === "blue" ||
                computedAccent === "violet"
              ) {
                accentColors.blue = "#38bdf8";
              }
              // INVARIANT: only none | fade | up reaches the timeline.
              var exit = vars.exit === "fade" || vars.exit === "up" ? vars.exit : "none";

              root.dataset.register = register;
              root.style.setProperty("--ir-accent", accentColors[accent]);
              root.style.setProperty("--ir-cx", irisX + "%");
              root.style.setProperty("--ir-cy", irisY + "%");

              // Geometry measured in px ONCE at mount (cq units inside tweened
              // values are a seek trap). The full radius clears the farthest
              // frame corner with a small margin so the landed frame has no
              // visible clip edge.
              var width = root.clientWidth || 1920;
              var height = root.clientHeight || 1080;
              var centerX = (irisX / 100) * width;
              var centerY = (irisY / 100) * height;
              var fullRadius =
                Math.hypot(Math.max(centerX, width - centerX), Math.max(centerY, height - centerY)) *
                  1.02 +
                2;

              rim.setAttribute("viewBox", "0 0 " + width + " " + height);
              rimCircle.setAttribute("cx", String(centerX));
              rimCircle.setAttribute("cy", String(centerY));
              rimCircle.setAttribute("stroke-width", String(Math.max(2, width * 0.0021)));

              // RETIME RANGE: fixed IN and OUT scale together only when D is too
              // short. HOLD is the sole elastic phase. Never use timeScale().
              var STAGE_IN_BASE = 0.32;
              var OPEN_DURATION_BASE = 1.1;
              var IN_BASE = openAt + OPEN_DURATION_BASE;
              var OUT_BASE = exit === "none" ? 0 : 0.5;

              var duration = Math.max(0.001, parseFloat(root.dataset.duration || "3.5"));
              var totalBase = IN_BASE + OUT_BASE;
              var scale = duration < totalBase ? duration / totalBase : 1;
              var IN = IN_BASE * scale;
              var OUT = OUT_BASE * scale;
              var STAGE_IN = Math.min(STAGE_IN_BASE * scale, IN);
              var OPEN_AT = openAt * scale;
              var OPEN_DURATION = OPEN_DURATION_BASE * scale;
              var OPEN_END = IN;
              var HOLD = Math.max(0, duration - (IN + OUT));
              var OUT_START = IN + HOLD;

              function fireSfx(id, t) {
                root.dispatchEvent(
                  new CustomEvent("hf:sfx", { detail: { id: id, t: t }, bubbles: true }),
                );
              }

              // ONE radius proxy owns both the clip-path and the rim ring, so
              // the two edges are locked on every frame. Seeded before the
              // timeline builds so tl.seek(0) shows the closed iris.
              var radius = { value: 0 };
              function writeIris() {
                after.style.setProperty("--ir-r", String(radius.value));
                rimCircle.setAttribute("r", String(Math.max(0, radius.value)));
              }
              writeIris();

              // Explicit both-endpoints state makes tl.seek(0) deterministic.
              gsap.set(stage, { opacity: 0, y: 0 });
              gsap.set(rim, { autoAlpha: 0 });

              var tl = gsap.timeline({ paused: true });

              // IN: stage settle, then ONE confident iris pass (quiet register,
              // L2). The rim fades in as the pass starts and dissolves just
              // before the iris clears the frame corners.
              tl.to(stage, { opacity: 1, duration: STAGE_IN, ease: "power2.out" }, 0);
              tl.fromTo(
                radius,
                { value: 0 },
                {
                  value: fullRadius,
                  duration: OPEN_DURATION,
                  ease: "power2.inOut",
                  onUpdate: writeIris,
                },
                OPEN_AT,
              );
              tl.fromTo(
                rim,
                { autoAlpha: 0 },
                {
                  autoAlpha: 1,
                  duration: Math.min(0.18 * scale, OPEN_DURATION),
                  ease: "power1.out",
                  immediateRender: false,
                },
                OPEN_AT,
              );
              tl.to(
                rim,
                { autoAlpha: 0, duration: 0.24 * scale, ease: "power1.in" },
                Math.max(OPEN_AT, OPEN_END - 0.24 * scale),
              );
              tl.call(
                function () {
                  fireSfx("iris-land-soft", OPEN_END);
                },
                [],
                OPEN_END,
              );

              // HOLD: deliberately still on the revealed state B.

              // OUT: only when the exit variable asks for one; exit none holds
              // the final revealed frame (frame roots own transitions).
              if (exit !== "none") {
                tl.to(stage, { opacity: 0, duration: OUT, ease: "power2.in" }, OUT_START);
                if (exit === "up") {
                  tl.to(stage, { y: "-6cqh", duration: OUT, ease: "power2.in" }, OUT_START);
                }
              }

              tl.seek(0);

              window.__timelines = window.__timelines || {};
              window.__timelines[compositionId] = tl;
            })();
          </script>
        </div>
      </template>
    </body>
  </html>
  ```
</Accordion>

Tagged `transition` `iris` `circle-reveal` `clip-path` `bridge` `slots`.

## Related topics

* [Browse the complete Catalog](/catalog)
* [Add assets and Catalog items in Studio](/studio/assets-and-blocks)
* [Build a richer composition](/go-further)


## Related topics

- [SDF Iris](/catalog/blocks/sdf-iris.md)
- [Transitions](/prompting/transitions.md)
- [Particle Image Reveal](/catalog/components/particle-image-reveal.md)
