hyperframes/docs/concepts/compositions.mdx

---
title: Compositions
description: "The fundamental building block of a Hyperframes video."
---

A composition is an HTML document that defines a video timeline. Every clip -- video, image, audio -- lives inside a composition.

## Structure

Every composition needs a root element with `data-composition-id`:

```html index.html
<div id="root" data-composition-id="root"
     data-start="0" data-width="1920" data-height="1080">
  <!-- Elements go here -->
</div>
```

The `index.html` file is the top-level composition. It can contain nested compositions within it. Any composition can be imported into another -- there is no special "root" type.

## Clip Types

A clip is any discrete block on the timeline, represented as an HTML element with [data attributes](/concepts/data-attributes):

- `<video>` -- Video clips, B-roll, A-roll
- `<img>` -- Static images, overlays
- `<audio>` -- Music, sound effects
- `<div data-composition-id="...">` -- Nested compositions (animations, grouped sequences)

See the [HTML Schema Reference](/reference/html-schema) for the full list of attributes on each clip type.

## Nested Compositions

You can embed one composition inside another in two ways: loading from an external file or defining it inline. External files are the recommended approach for reusable compositions.

<Tabs>
  <Tab title="External file">
    Reference another HTML file with `data-composition-src`. The framework automatically fetches the file, extracts the `<template>` content, mounts it, executes scripts, and registers the timeline.

    ```html index.html
    <div
      id="el-5"
      data-composition-id="intro-anim"
      data-composition-src="compositions/intro-anim.html"
      data-start="0"
      data-track-index="3"
    ></div>
    ```

    Each external composition file wraps its content in a `<template>` tag:

    ```html compositions/intro-anim.html
    <template id="intro-anim-template">
      <div data-composition-id="intro-anim" data-width="1920" data-height="1080">
        <div class="title">Welcome!</div>

        <style>
          [data-composition-id="intro-anim"] .title {
            font-size: 72px; color: white; text-align: center;
          }
        </style>

        <script>
          const tl = gsap.timeline({ paused: true });
          tl.from(".title", { opacity: 0, y: -50, duration: 1 });
          window.__timelines["intro-anim"] = tl;
        </script>
      </div>
    </template>
    ```
  </Tab>
  <Tab title="Inline">
    Define a nested composition directly inside the parent. This is simpler for one-off compositions that do not need to be reused.

    ```html index.html
    <div id="root" data-composition-id="root"
         data-start="0" data-width="1920" data-height="1080">

      <!-- Inline nested composition -->
      <div id="el-5" data-composition-id="intro-anim"
           data-start="0" data-track-index="3"
           data-width="1920" data-height="1080">
        <div class="title">Welcome!</div>
      </div>

      <script>
        // Timeline for the inline composition
        const introTl = gsap.timeline({ paused: true });
        introTl.from(".title", { opacity: 0, y: -50, duration: 1 });
        window.__timelines["intro-anim"] = introTl;
      </script>
    </div>
    ```

    Inline compositions do not use `<template>` tags or `data-composition-src`.
  </Tab>
</Tabs>

### Project Structure

<Tree>
  <Tree.Folder name="project" defaultOpen>
    <Tree.File name="index.html" />
    <Tree.Folder name="compositions" defaultOpen>
      <Tree.File name="intro-anim.html" />
      <Tree.File name="caption-overlay.html" />
      <Tree.File name="outro-title.html" />
    </Tree.Folder>
    <Tree.Folder name="assets">
      <Tree.File name="video.mp4" />
      <Tree.File name="music.mp3" />
      <Tree.File name="logo.png" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## Two Layers: Primitives and Scripts

Every composition has two layers:

- **HTML** -- primitive clips (`video`, `img`, `audio`, nested compositions). The declarative structure: what plays, when, and on which track. Controlled by [data attributes](/concepts/data-attributes).
- **Script** -- effects, transitions, dynamic DOM, canvas, SVG -- creative animation via [GSAP](/guides/gsap-animation). Scripts do **not** control media playback or clip visibility.

<Warning>
  Never use scripts to play/pause/seek media elements or to show/hide clips based on timing. The framework handles this automatically from data attributes. Scripts that duplicate this behavior will conflict with the framework. See [Common Mistakes](/guides/common-mistakes) for examples.
</Warning>

## Variables

HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM or CSS.

The supported pattern is:

1. Declare the variables once on the sub-comp's `<html>` root with `data-composition-variables` (id + type + default).
2. Pass per-instance values on each composition host with `data-variable-values`.
3. Read the resolved values inside the composition with `window.__hyperframes.getVariables()`. The runtime layers the host's `data-variable-values` over the declared defaults on a per-instance basis, so the same source can be embedded multiple times with different values.

```html index.html
<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-start="0"
  data-track-index="1"
  data-variable-values='{"title":"Pro","color":"#ff4d4f"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-start="card-pro"
  data-track-index="1"
  data-variable-values='{"title":"Enterprise","color":"#22c55e"}'
></div>
```

```html compositions/card.html
<html data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Fallback"},
  {"id":"color","type":"color","label":"Color","default":"#111827"}
]'>
  <body>
    <div data-composition-id="card" data-width="1920" data-height="1080">
      <h1 class="title"></h1>

      <style>
        [data-composition-id="card"] {
          --card-color: #111827;
        }

        [data-composition-id="card"] .title {
          color: var(--card-color);
        }
      </style>

      <script>
        // Inside a sub-comp script, getVariables() returns the per-instance
        // values: declared defaults < host data-variable-values overrides.
        const { title, color } = __hyperframes.getVariables();
        const root = document.querySelector('[data-composition-id="card"]');
        root.querySelector(".title").textContent = title;
        root.style.setProperty("--card-color", color);
      </script>
    </div>
  </body>
</html>
```

If you are building tooling on top of `@hyperframes/core`, the same `data-composition-variables` array is readable via `extractCompositionMetadata()` for Studio editing UI and analysis pipelines.

## Listing Compositions

Use the [CLI](/packages/cli) to see all compositions in a project:

```bash
npx hyperframes compositions
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Attributes" icon="code" href="/concepts/data-attributes">
    Full reference for timing, media, and composition attributes
  </Card>
  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
    Add animations to your compositions with GSAP timelines
  </Card>
  <Card title="Examples" icon="grid-2" href="/examples">
    Start from built-in examples for common video patterns
  </Card>
  <Card title="HTML Schema Reference" icon="book" href="/reference/html-schema">
    Complete schema for authoring compositions
  </Card>
</CardGroup>