--- 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 Studio can create and bind variables, preview overrides, and copy the reviewed values into a render command. Follow [Use variables and templates](/studio/variables) for that complete workflow. ## Advanced: declare the approved inputs Variables live on the composition declaration: ```html compositions/card.html ``` 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. ### 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: ```html compositions/card.html {"id":"appName","type":"string","label":"App name", "description":"Name of the brand this video promotes, credited in the corner of every banner.", "portrays":["subject_name"],"default":"HyperFrames"} ``` | Value | The slot stands for | | ---------------------- | -------------------------------------------------------------------------- | | `subject_name` | The promoted brand's own name | | `subject_domain` | Its domain, URL, or handle | | `subject_tagline` | Its own positioning line | | `subject_logo` | Its mark or wordmark | | `recommended_position` | The winning or featured slot in a ranking, so the promoted brand goes there | | `competitor_name` | A real product other than the promoted brand | | `authority_badge` | A claim of endorsement, ranking authority, rating, or source | | `host_identity` | The depicted application's own identity, which a remix leaves alone | `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: ```html

Pro

``` - `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

``` Both instances keep the same source and receive different content. ## Advanced: 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. ### Batch renders Put one variable object per row in a JSON array, then use placeholders from the row to name each output: ```json rows.json [ { "name": "acme", "title": "Acme Pro" }, { "name": "northstar", "title": "Northstar Pro" } ] ``` ```bash npx hyperframes render \ --batch rows.json \ --strict-variables \ --output "renders/{name}.mp4" ``` 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: ```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.