Skip to main content
Variables expose the parts of a composition that are meant to change. One customer card can accept a different name, logo, color, and plan while keeping the same layout and motion. Use a variable when the design should remain stable across versions. Make a normal source edit when the structure itself needs to change.
Default values
The same design with different values

​
Use variables in Studio

Studio can create and bind variables, preview overrides, and copy the reviewed values into a render command. Follow Use variables and templates for that complete workflow.

​
Advanced: declare the approved inputs

Variables live on the composition declaration:
compositions/card.html
Supported declared types are: The type lets Studio show the right control and lets rendering catch invalid values.

​
Say what a slot means, not where it sits

label and description are read by people and by agents. A description that only gives a position (“small credit in the corner of every banner”) leaves the slot’s meaning to be guessed; one that gives the meaning (“name of the brand this video promotes”) can be filled correctly without opening the HTML. For a template that will be remixed against someone else’s brand, add portrays — a list naming what the slot stands for. It is optional metadata, ignored by rendering, and it tells an editing agent which slots carry identity and must not be filled with invented copy:
compositions/card.html
portrays is orthogonal to role: role says which aspect of the composition a knob affects (content, style, timing, motion, layout), while portrays says what the value means to a viewer.

​
Bind common values without a script

Use direct bindings for the normal cases:
  • data-var-text replaces the element’s own text.
  • data-var-src replaces an image, video, audio, or source URL.
  • Scalar variables are available as CSS custom properties such as var(--accent).
Use window.__hyperframes.getVariables() only when the result needs conditions, loops, or derived values:

​
Give each nested composition different values

A parent can reuse the same composition several times:
index.html
Both instances keep the same source and receive different content.

​
Advanced: render a version from data

Override top-level values from the CLI:
Use --variables-file for a JSON file and --batch when the same composition must render once per data row. The CLI reference covers batch output, validation, and automation.

​
Batch renders

Put one variable object per row in a JSON array, then use placeholders from the row to name each output:
rows.json
Start with the default single-row concurrency. Increase --batch-concurrency only after one real render is stable and the machine has enough memory for several renders at once.

​
What can’t be a variable

Variables change content inside a composition. They do not change:
  • the composition viewport;
  • the root composition’s total render duration;
  • frame rate;
  • output format, codec, or quality;
  • a parent or sibling composition unless values are passed to it explicitly.
Those choices are read from source or render settings before composition logic runs.

​
Check the contract

Run:
The linter catches malformed declarations, missing fields, wrong default types, and invalid enum choices. --strict-variables turns undeclared or mistyped render values into errors. Continue to Compositions for nesting or the HTML schema for the complete attribute contract.