Features

Everything Iris does, in depth

Launcher Pill

Wrapping an app doesn't take it over. The page renders untouched — native scroll, keyboard, and inputs — with a small iris pill in the bottom-right corner. Click it to wrap the page in the cinematic stage; click exit to hand the page back. The app keeps rendering into the same DOM host in both states, so its state survives the round trip. The toggle persists per storageKey; defaultActive overrides the starting state (standalone mode defaults to active), and ref.setActive(bool) drives it programmatically.

Camera Controls

Drag to pan, Alt+drag to orbit, scroll to zoom, Alt+scroll to tilt. An orientation gizmo in the corner shows the current camera rotation and snaps back to front-on with a click. The right panel exposes every camera value — tx, ty, rx, ry, rz, zoom — as scrubbable sliders, plus eight camera presets on ⌘1–8.

Animation Timeline

The bottom toolbar is a keyframe timeline for camera sequences:

  • + opens the pattern picker (built-in cinematic moves or a blank custom sequence)
  • Track — click/drag to scrub; the camera follows live
  • Keyframes — drag diamonds to retime (snaps to 0.05s, hold ⇧ for free), click to jump the camera to that stop
  • Inspector — select a keyframe to edit its time, the easing of its outgoing segment, capture the current camera into it, or delete it
  • Transport — go-to-start, play/pause from the playhead, loop, duration (rescales keyframes proportionally)
  • Add keyframe captures the current camera at the playhead

Sequences are stored as absolute camera positions with per-keyframe times and easings:

interface TimelineStop {
id: string
time: number // seconds
vals: CameraValues // absolute camera position
easing: string // easing into the next stop
}

Pre-timeline saved sequences (evenly spaced stops, single global easing) are migrated automatically on load.

Camera Patterns

Built-in cinematic moves seed the timeline with one click: truck, crane, pan, orbit, dolly zoom, hero intro, flyover, and more. Each pattern is relative to the current camera, so it composes with whatever framing you've set up. Patterns can be mirrored or direction-swapped from the sequence editor.

Live — the actual BUILT_IN_PATTERNS factories, sampled with sampleSequenceAt and scaled to fit the card.

Depth of Field

Four blur modes, each rendered as masked CSS blur layers over the staged content:

  • Directional — blur ramps along an angle you set
  • Radial — sharp center, blurred edges
  • Tilt-shift — a sharp band with blur above and below, the classic miniature look
  • Lens — simulated focus falloff
Live — the real masked backdrop-blur layers from applyDof, cycling through all four modes while the focus point drifts.

On the WebGL engine, DOF becomes true bokeh with a focus point and physical falloff instead of layered CSS blur.

WebGL Engine

The default engine renders with pure CSS transforms — zero three.js in your bundle. The opt-in WebGL engine (@alstroemeria/iris/three) adds true bokeh depth of field, focus-point falloff, and procedural 3D scene presets that place your app inside a modeled environment.

import { WebglEngine } from "@alstroemeria/iris/three";
<Iris engines={{ webgl: WebglEngine }}>{children}</Iris>

It requires four extra peers — see Install — and is what this docs site runs: press the launcher pill (or the Stage this page button on the overview) and switch the panel to the WEBGL engine.

Content Sources

With no children, the stage shows a drop zone. Load content by pasting a URL, dropping a file (images persist as data URLs, videos play for the session), or uploading via the left panel's Content section.

InputResult
example.comhttps:// prepended, loaded as iframe
youtube.com/watch?v=…, youtu.be/…, shortsYouTube embed player (autoplay, muted, looped)
vimeo.com/123…Vimeo embed player
loom.com/share/…Loom embed
figma.com/file|proto|design/…Figma embed viewer
codepen.io/u/pen/…, codesandbox.io/s/…Result-view embeds
*.png .jpg .webp .svg …Image (sized to natural dimensions)
*.mp4 .webm .mov …Video (autoplay, muted, looped)

Programmatic equivalents are exported:

import { parseContentUrl, toEmbedUrl } from "@alstroemeria/iris";
// Or pass an initial source:
<Iris content={{ kind: "embed", url: "https://example.com" }} />

Some sites refuse to render in iframes (X-Frame-Options / CSP). The embed rewrites above avoid that for popular services; for anything else you'll see a blank frame — use a screenshot or video capture of the site instead. Toggle Interactive embed off in the Content section to let camera drags pass through the iframe.

Window Chrome

Frame the staged content in a Safari-style browser bar or a plain window title bar, with size presets covering social formats, devices, and displays. ⌘⇧F toggles frame mode.

Backgrounds

All backgrounds are generated algorithmically — solid colors, linear gradients, and noise gradients from RGB tuples and angles. No image assets ship with the package. Presets are exported as GRADIENT_PRESETS, NOISE_GRADIENT_PRESETS, and COLOR_PRESETS, with bgToCSS() to convert a config to CSS.

Live — NOISE_GRADIENT_PRESETS rendered through bgToCSS(), one per loop of the Breathe pattern. No image assets.

Entrance Animations

With the optional motion peer installed, Iris plays a staggered entrance reveal. It auto-detects shadcn data-slot elements and falls back to semantic HTML — or pass your own selectors:

<Iris
animations={[
{ selector: '[data-slot="card"]', y: 20, stagger: 0.06 },
{ selector: "tbody tr", x: -14, blur: 6, stagger: 0.04 },
]}
>

⌘⇧⏎ replays the entrance at any time.

Export

⌘⇧S captures the staged scene as a 2× PNG (requires the optional modern-screenshot peer). For motion, recordElementWhile records an element to video for the duration of a callback — point it at the stage while a sequence plays. captureElementBlob, copyBlobToClipboard, and downloadBlob are exported for custom export flows.

Headless Mode

Use the hooks directly for custom UIs:

import { useIris, useCameraTween, sampleSequenceAt } from "@alstroemeria/iris";
function MyCustomViewer({ children }) {
const { vals, setVals, transform, dofRefs, dofClasses } = useIris();
// Build your own controls...
}

useCameraTween drives sequence playback, sampleSequenceAt samples a sequence at an arbitrary time, and useSequences manages saved sequences. The panel components (CameraPanel, LeftPanel, Timeline) are exported individually too.

Keyboard Shortcuts

Press ⌘/ in the app for the full reference.

KeyAction
Space + dragPan
Alt + dragOrbit
⌘ scrollZoom
Alt scrollTilt
⌘ ⏎Play / pause sequence
⌘ ⇧ ⏎Play entrance
⌘ 1–8Camera presets
⌘ ⇧ SScreenshot
⌘ ⇧ FFrame mode
⌘ .Toggle panels
HHide cursor

Persistence

Camera, content, background, and sequences persist in localStorage. Use distinct storageKey values per surface (e.g. iris:studio, iris:landing) so setups don't collide, or pass persist={false} to disable.