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: stringtime: number // secondsvals: CameraValues // absolute camera positioneasing: 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.
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
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.
| Input | Result |
|---|---|
example.com | https:// prepended, loaded as iframe |
youtube.com/watch?v=…, youtu.be/…, shorts | YouTube 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.
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:
<Irisanimations={[{ 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.
| Key | Action |
|---|---|
| Space + drag | Pan |
| Alt + drag | Orbit |
| ⌘ scroll | Zoom |
| Alt scroll | Tilt |
| ⌘ ⏎ | Play / pause sequence |
| ⌘ ⇧ ⏎ | Play entrance |
| ⌘ 1–8 | Camera presets |
| ⌘ ⇧ S | Screenshot |
| ⌘ ⇧ F | Frame mode |
| ⌘ . | Toggle panels |
| H | Hide 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.