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

Compositions can expose variables for dynamic content:

```html compositions/card.html
<div data-composition-id="card" data-var-title="string" data-var-color="color">
```

Variables make compositions reusable as [examples](/examples) -- the same composition can render different content by injecting variable values at render time.

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