Setting the file. One moment.
Subchapter 21.7
references/sub-compositions.mdMarkdown8 KBView on GitHub
A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at data-start.
In the host composition, the sub-composition appears as a clip with data-composition-src:
<div
id="chart"
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="8"
data-track-index="2"
data-width="1920"
data-height="1080"
></div>data-composition-id on the host must match the internal data-composition-id of the file at data-composition-src.data-start, data-duration, data-track-index, data-width, data-height.When a host loads a sub-composition via data-composition-src, the runtime:
fetches the HTML file.DOMParser.<template> element and clones ONLY its contents into the host slot.<template> (including the entire <head>) is discarded.So <template> is not just a wrapper — it is the transport container. If a node needs to exist in the live render, it must be inside <template>. Full stop.
<!doctype html>
<html>
<head>
<meta charset="UTF-8" />
<!-- head is metadata for the source file only; the runtime ignores it -->
</head>
<body>
<template>
<!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
<style>
/* Root: style by #root, never a class. lint: subcomposition_root_styled_by_class. See Pitfall 3. */
#root {
position: absolute;
inset: 0;
color: #fff;
}
/* .label, #bar, … — descendants, plain selectors */
</style>
<div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
<!-- sub-composition markup -->
</div>
<script>
const tl = gsap.timeline({ paused: true });
// ... build timeline ...
window.__timelines["data-chart"] = tl;
</script>
</template>
</body>
</html>Contrast with standalone compositions, which put the root directly in <body> with no <template> wrapper.
Static file checks cannot prove the cross-file mount contract. These failures appear only when the runtime mounts the sub-composition.
<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
<head>
<style>
#root { font-size: 88px; ... }
</style>
</head>
<body>
<template>
<div id="root" data-composition-id="data-chart" ...>...</div>
</template>
</body>
<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
<head></head>
<body>
<template>
<style>
#root { font-size: 88px; ... }
</style>
<div id="root" data-composition-id="data-chart" ...>...</div>
</template>
</body>Why this happens: standard HTML conventions tell you to put <style> in <head>. In a standalone HTML file that’s correct. In a HyperFrames sub-composition it is not — the runtime only clones <template> contents, so <head><style> is dropped on the floor.
Symptom: isolated checks pass and the render completes, but every text element appears as tiny unstyled default text in the top-left and SVGs expand to canvas size because no CSS reached the live DOM. The same trap applies to <script> blocks, <link rel="stylesheet">, and custom-element registrations: anything that must execute or apply in the render belongs inside <template>.
<!-- ❌ WRONG — host renames the slot; runtime can't find the timeline -->
<!-- host file (e.g. index.html) -->
<div data-composition-id="chart-mount" data-composition-src="compositions/chart.html" ...></div>
<!-- chart.html -->
<template>
<div data-composition-id="data-chart" ...>...</div>
<script>
window.__timelines["data-chart"] = tl;
</script>
</template>
<!-- ✅ RIGHT — both ids match, and the timeline key matches them too -->
<div data-composition-id="data-chart" data-composition-src="compositions/chart.html" ...></div>
<!-- chart.html template root: data-composition-id="data-chart" -->
<!-- timeline: window.__timelines["data-chart"] = tl; -->Why this happens: it feels natural to give the host slot a different name like chart-mount (“the mount point”) vs data-chart (“the actual chart”). HyperFrames does not work that way — the host’s data-composition-id is the lookup key the framework uses to find the registered timeline. Lint passes because each file’s ids are individually valid; the cross-file mismatch only blows up at render.
Symptom: the render logs Sub-composition timelines not registered after 45000ms: <host-id> for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
lint still errors (subcomposition_root_styled_by_class) if a sub-composition styles the host root’s own class. Style the root with #root.
data-composition-id.data-start of the host clip, for data-duration seconds.Do not manually master.add(child) a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
data-duration on the host clip defines how long the slot is visible, and it takes precedence over the sub-composition’s internal GSAP timeline length. Two consequences follow:
data-duration elapses, the slot keeps showing its final frame for the rest of the window. You do not need to pad the timeline with empty tweens.data-duration shorter than the host composition → the slot ends (and goes blank) when its own data-duration elapses. This is intended: the clip is a fixed-length window on the timeline, not “fill until the composition ends.” To keep a sub-composition visible for the whole composition, set its data-duration to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as subcomposition_blanks_before_host.Prefer gsap.fromTo() over gsap.from() for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; gsap.from() records the starting state at registration and can desync on seek-back, while gsap.fromTo() declares both endpoints explicitly and replays cleanly.
If the sub-composition declares variables on its <html> element (data-composition-variables), the host can override values per instance:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-variable-values='{"title":"Q4 Revenue","accent":"#66d9ef"}'
data-start="2"
data-duration="8"
data-track-index="2"
data-width="1920"
data-height="1080"
></div>The host can render the same sub-composition multiple times with different data-variable-values to produce per-instance variations. See variables-and-media.md for variable declaration syntax.