Getting Started

hyperbits is a catalog of self-contained HTML + GSAP animation bits for HyperFrames. Each bit is a composition file with its own CSS, paused timeline, and data-composition-variables.

Installation

The package is published to GitHub Packages as @av/hyperbits. GitHub Packages needs a token even for public packages, so set up npm once:

gh auth refresh -h github.com -s read:packages
npm config set @av:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken "$(gh auth token)"

Without the gh CLI, create a classic token with the read:packages scope at https://github.com/settings/tokens/new?scopes=read:packages and use it in place of $(gh auth token).

CLI

Search and add bits from a HyperFrames project:

npx @av/hyperbits find "fade in text"
npx @av/hyperbits add fade-in

add writes compositions/fade-in.html and prints a data-composition-src snippet.

hyperframes add

Point the project registry at the hyperbits catalog, then use the HyperFrames CLI:

hyperframes.json

{
  "registry": "https://hyperbits.pages.dev"
}

npx hyperframes add fade-in

npm

npm install @av/hyperbits

MCP

mcp.json

{
  "mcpServers": {
    "hyperbits": {
      "command": "npx",
      "args": ["-y", "@av/hyperbits", "mcp"]
    }
  }
}

Prerequisites

Bits load GSAP themselves from:

https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js

Helpers ship as hyperbits.iife.js. hyperbits add and hyperframes add write it next to each bit, and it is also served at https://hyperbits.dev/vendor/hyperbits.iife.js. HyperFrames does not inject it.

Note

Need a HyperFrames project first? Run npx hyperframes init.

Embed a bit

After hyperbits add fade-in (or hyperframes add fade-in), compositions/ holds fade-in.html and the hyperbits.iife.js it loads. Embed the bit:

<div data-composition-src="compositions/fade-in.html"></div>

Override knobs declared in data-composition-variables with data-variable-values on the host, or --variables on hyperframes render.

Background layer

Never paint on the composition root. The HyperFrames renderer drops background on the data-composition-id element, so standalone frames go transparent. Put a full-bleed #bg layer as the first child (data-start="0", data-duration equal to the bit, literal background-color). Keep html, body backgrounds for Studio preview. Animate gradients on #bg, not on #root.

Helpers

The same helpers bits use are available as ES modules:

import { interpolate, stagger, viewport } from '@av/hyperbits/helpers';

or on the IIFE global hyperbits inside a composition <script>.

Next steps

1. Browse the catalog
2. Read the CLI and MCP pages
3. Use a helper from the reference