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.

​
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 named --hf-var-<slug>, so the accent variable above is read as var(--hf-var-accent).
The slug is the id lowercased, with anything that is not a letter, digit or hyphen replaced by a hyphen. So accentColor is readable as var(--hf-var-accentcolor), and swap_at as var(--hf-var-swap-at).
How a variable is named in CSS. Every scalar variable is written to --hf-var-<slug>. It is also written to the bare --<slug>, but only when the id is not one of the fifteen reserved theme-token names: accent, accent-2, accent-3, accent2, bg, border, brand, fg, ink, muted, primary, secondary, surface, tertiary, text. Those names belong to the page hosting the composition, so a variable never writes them. A variable called accent cannot shadow the host theme’s --accent.The bare --<slug> alias is deprecated and will be removed in a future release. Bind var(--hf-var-<slug>) in new work. When a value should follow the host theme if there is one and fall back to the declared variable otherwise, write var(--accent, var(--hf-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.