HyperFrames Registry
The registry provides reusable blocks and components installable via hyperframes add <name>.
- Blocks — standalone sub-compositions (own dimensions, duration, timeline). Included via
data-composition-src in a host composition.
- Components — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.
Quick reference
hyperframes add data-chart # install a block
hyperframes add grain-overlay # install a component
hyperframes add shimmer-sweep --dir . # target a specific project
hyperframes add data-chart --json # machine-readable output
hyperframes add data-chart --no-clipboard # skip clipboard (CI/headless)
After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add data-composition-id (must match the block's internal composition ID), data-start, and data-track-index attributes when wiring blocks.
Note: hyperframes add only works for blocks and components. For examples, use hyperframes init <dir> --example <name> instead.
Install locations
Blocks install to compositions/<name>.html by default.
Components install to compositions/components/<name>.html by default.
These paths are configurable in hyperframes.json:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
See install-locations.md for full details.
Wiring blocks
Blocks are standalone compositions — include them via data-composition-src in your host index.html:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
Key attributes:
data-composition-src — path to the block HTML filedata-composition-id — must match the block's internal IDdata-start — when the block appears in the host timeline (seconds)data-duration — how long the block playsdata-width / data-height — block canvas dimensionsdata-track-index — layer ordering (higher = in front)
See wiring-blocks.md for full details.
Wiring components
Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):
- Read the installed file (e.g.,
compositions/components/grain-overlay.html)
- Copy the HTML elements into your composition's
<div data-composition-id="...">
- Copy the
<style> block into your composition's styles
- Copy any
<script> content into your composition's script (before your timeline code)
- If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline
See wiring-components.md for full details.
Discovery
Browse available items:
# Read the registry manifest
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Each item's registry-item.json contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.
See discovery.md for details on filtering by type and tags.
Contributing a new block or component
To author a NEW registry item (caption style, VFX block, transition, lower third, or a reusable component) and ship it as an upstream PR — not install an existing one — follow the full idea → scaffold → build → validate → preview → ship workflow in contributing.md. Copy-paste starter templates (caption / VFX / component / registry-item.json) are in templates.md.
