mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
ukimsanov
148 lines
4.2 KiB
Plaintext
148 lines
4.2 KiB
Plaintext
---
|
||
title: "Reuse a design with variables"
|
||
sidebarTitle: "Variables"
|
||
description: "Change approved text, colors, media, and choices without rebuilding the composition."
|
||
---
|
||
|
||
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.
|
||
|
||
## Use variables in Studio
|
||
|
||
Open **Variables** for the active composition. You can:
|
||
|
||
- add or edit a declared value;
|
||
- preview custom values without rewriting the layout;
|
||
- see where a variable is used;
|
||
- bind a selected text, media, or style value;
|
||
- copy the effective values as JSON or a render command;
|
||
- render with the values currently being previewed.
|
||
|
||
Give every variable a clear label and a useful default. A person should
|
||
understand what changing it will do before touching the value.
|
||
|
||
## Declare the approved inputs
|
||
|
||
Variables live on the composition declaration:
|
||
|
||
```html compositions/card.html
|
||
<html data-composition-variables='[
|
||
{"id":"title","type":"string","label":"Title","default":"Pro"},
|
||
{"id":"accent","type":"color","label":"Accent color","default":"#6c5ce7"},
|
||
{"id":"logo","type":"string","label":"Logo","default":"assets/logo.svg"}
|
||
]'>
|
||
```
|
||
|
||
Supported declared types are:
|
||
|
||
| Type | Good for |
|
||
| --- | --- |
|
||
| `string` | Text or a media path |
|
||
| `number` | Counts, positions, sizes, or strengths |
|
||
| `color` | Approved color choices |
|
||
| `boolean` | On or off |
|
||
| `enum` | One value from an approved list |
|
||
| `font` | A font-family choice |
|
||
| `image` | An image path or image value |
|
||
|
||
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:
|
||
|
||
```html
|
||
<h1 data-var-text="title">Pro</h1>
|
||
|
||
<img data-var-src="logo" src="assets/logo.svg" alt="" />
|
||
|
||
<style>
|
||
.card-title {
|
||
color: var(--accent);
|
||
}
|
||
</style>
|
||
```
|
||
|
||
- `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:
|
||
|
||
```js
|
||
const { featured = false } = window.__hyperframes.getVariables();
|
||
document.querySelector(".badge").hidden = !featured;
|
||
```
|
||
|
||
## Give each nested composition different values
|
||
|
||
A parent can reuse the same composition several times:
|
||
|
||
```html index.html
|
||
<div
|
||
data-composition-id="card-pro"
|
||
data-composition-src="compositions/card.html"
|
||
data-start="0"
|
||
data-variable-values='{"title":"Pro","accent":"#ff4d4f"}'
|
||
></div>
|
||
|
||
<div
|
||
data-composition-id="card-enterprise"
|
||
data-composition-src="compositions/card.html"
|
||
data-start="card-pro"
|
||
data-variable-values='{"title":"Enterprise","accent":"#22c55e"}'
|
||
></div>
|
||
```
|
||
|
||
Both instances keep the same source and receive different content.
|
||
|
||
## Render a version from data
|
||
|
||
Override top-level values from the CLI:
|
||
|
||
```bash
|
||
npx hyperframes render \
|
||
--variables '{"title":"Enterprise","accent":"#22c55e"}' \
|
||
--strict-variables \
|
||
--output enterprise.mp4
|
||
```
|
||
|
||
Use `--variables-file` for a JSON file and `--batch` when the same composition
|
||
must render once per data row. The [CLI reference](/packages/cli) covers batch
|
||
output, validation, and automation.
|
||
|
||
## Know what variables do not control
|
||
|
||
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:
|
||
|
||
```bash
|
||
npx hyperframes lint
|
||
```
|
||
|
||
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](/concepts/compositions) for nesting or the
|
||
[HTML schema](/reference/html-schema) for the complete attribute contract.
|