From a9b4745f1f9773cc0dcd1f6d81b942ce97335f87 Mon Sep 17 00:00:00 2001 From: Robin Ebers Date: Wed, 18 Nov 2026 04:10:18 +0000 Subject: [PATCH] feat(player): add customizable branding to the preview player (#7718) A page that embeds can now give it its own play, pause and volume icons and its own loading logo, by putting elements with a slot attribute inside the player. Anything the page leaves out keeps today's HyperFrames look. Co-authored-by: robinebers <16515780+robinebers@users.noreply.github.com> Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/packages/player.mdx | 35 +++++ packages/player/README.md | 49 +++++++ packages/player/src/controls.test.ts | 121 +++++++++++++++++- packages/player/src/controls.ts | 35 +++-- .../player/src/hyperframes-player.test.ts | 54 ++++++++ packages/player/src/shader-loader-element.ts | 7 +- scripts/package-size-budgets.json | 4 +- 7 files changed, 287 insertions(+), 18 deletions(-) diff --git a/docs/packages/player.mdx b/docs/packages/player.mdx index 65197803a3..88155ca7ec 100644 --- a/docs/packages/player.mdx +++ b/docs/packages/player.mdx @@ -141,6 +141,41 @@ player.addEventListener("timeupdate", (event) => { | `error` | `{ message }` | Load or runtime error; a video adds its `MediaError` `code` | | `playbackerror` | `{ source, error }` | The browser blocked playback, for example unmuted autoplay | +## Custom icons and loading mark + +Put an element with a `slot` attribute inside the player to replace a control glyph or the loading mark. Anything you leave out keeps the default. + +| Slot | Shown when | Default size | +| ------------------- | ----------------------------------------------------------- | ------------ | +| `play-icon` | Paused | 24 px | +| `pause-icon` | Playing | 24 px | +| `volume-high-icon` | Unmuted, volume 0.5 or higher | 20 px | +| `volume-low-icon` | Unmuted, volume below 0.5 | 20 px | +| `volume-muted-icon` | Muted | 20 px | +| `loading-mark` | Preparing shader transitions, loading assets, and buffering | 78 px | + +```html title="index.html" + + + + + +``` + +Glyphs take the control bar's color through `currentColor`, and you set their size. Put `slot` on the `` or `` itself, as a direct child of the player; a wrapper element needs `display: contents` to keep the glyph centered. A custom mark replaces the HyperFrames light sweep and glow, so add your own CSS animation if you want motion. + +Until the element is defined, its children show as plain content. Hide them: + +```css title="styles.css" +hyperframes-player:not(:defined) > [slot] { + display: none; +} +``` + ## Advanced: iframe access The composition runs inside an `