Display and feedback

AsciinemaPlayer

SSR-safe terminal recording player with token-driven theme and fallback states.

Live example

Terminal demonstration

Usage

Each example includes the complete adapter-specific parameter reference. Copy it as a starting point, then remove options your use case does not need.

React

import { AsciinemaPlayer } from "@cofob/design-system-asciinema-player/react";

/**
 * Complete AsciinemaPlayer parameter reference.
 * @param source
 *   type: Source
 *   required
 *   example: "/recordings/demo.cast"
 * @param options
 *   type: Options
 *   default: { theme: "cofob" } plus upstream defaults
 *   example: {{ cols: 100, fit: "width" }}
 * @param label
 *   type: string
 *   default: "Terminal recording"
 *   example: "Accessible label"
 * @param fallbackHref
 *   type: string
 *   default: —
 *   example: "/recordings/demo"
 * @param labels
 *   type: Partial<AsciinemaPlayerLabels>
 *   default: English loading, error, and link defaults
 *   example: {{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }}
 * @param onPlayerReady
 *   type: (player: Player) => void
 *   default: —
 *   example: {handlePlayerReady}
 * @param onPlayerLoadError
 *   type: (error: unknown) => void
 *   default: —
 *   example: {handlePlayerLoadError}
 * @param figure attributes
 *   type: native element attributes
 *   default: —
 *   example: class / style / aria-* / data-*
 */
export function AsciinemaPlayerExample() {
  return (
    <AsciinemaPlayer source="/recordings/demo.cast" options={{ cols: 100, fit: "width" }} label="Deployment walkthrough" fallbackHref="/recordings/demo" labels={{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }} onPlayerReady={setPlayer} onPlayerLoadError={reportError} />
  );
}

Svelte

<script lang="ts">
  import { AsciinemaPlayer } from "@cofob/design-system-asciinema-player/svelte";

  // Complete AsciinemaPlayer parameter reference.
  // source
  //   type: Source
  //   required
  //   example: "/recordings/demo.cast"
  // options
  //   type: Options
  //   default: { theme: "cofob" } plus upstream defaults
  //   example: {{ cols: 100, fit: "width" }}
  // label
  //   type: string
  //   default: "Terminal recording"
  //   example: "Accessible label"
  // fallbackHref
  //   type: string
  //   default: —
  //   example: "/recordings/demo"
  // labels
  //   type: Partial<AsciinemaPlayerLabels>
  //   default: English loading, error, and link defaults
  //   example: {{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }}
  // player
  //   type: Player (bindable in Svelte)
  //   default: undefined
  //   example: bind:player
  // onPlayerReady
  //   type: (player: Player) => void
  //   default: —
  //   example: {handlePlayerReady}
  // onPlayerLoadError
  //   type: (error: unknown) => void
  //   default: —
  //   example: {handlePlayerLoadError}
  // figure attributes
  //   type: native element attributes
  //   default: —
  //   example: class / style / aria-* / data-*
</script>

<AsciinemaPlayer source="/recordings/demo.cast" options={{ cols: 100, fit: "width" }} label="Deployment walkthrough" fallbackHref="/recordings/demo" labels={{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }} bind:player onPlayerReady={setPlayer} onPlayerLoadError={reportError} />

HTML

<!--
  Complete AsciinemaPlayer parameter reference.
  source
    type: Source
    required
    example: "/recordings/demo.cast"
  options
    type: Options
    default: { theme: "cofob" } plus upstream defaults
    example: {{ cols: 100, fit: "width" }}
  label
    type: string
    default: "Terminal recording"
    example: "Accessible label"
  fallbackHref
    type: string
    default: —
    example: "/recordings/demo"
  labels
    type: Partial<AsciinemaPlayerLabels>
    default: English loading, error, and link defaults
    example: {{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }}
  onPlayerReady
    type: (player: Player) => void
    default: —
    example: {handlePlayerReady}
  onPlayerLoadError
    type: (error: unknown) => void
    default: —
    example: {handlePlayerLoadError}
  figure attributes
    type: native element attributes
    default: —
    example: class / style / aria-* / data-*
-->
<figure class="cf-asciinema-player" data-cf-asciinema-player data-state="loading" aria-label="Deployment walkthrough" aria-busy="true"><div class="cf-stack" data-gap="sm" data-align="stretch"><div class="cf-card cf-asciinema-player__stage" data-padding="none" data-variant="default" data-cf-asciinema-player-stage hidden><div data-cf-asciinema-player-mount></div></div><div class="cf-alert cf-asciinema-player__fallback" data-tone="info" role="status" data-cf-asciinema-player-fallback><div class="cf-alert__content"><div class="cf-alert__title" data-cf-asciinema-player-fallback-title>Terminal demo</div><div class="cf-alert__description"><a class="cf-link" href="/recordings/demo" data-cf-asciinema-player-fallback-link>Open recording</a></div></div></div></div></figure>

<script type="module">
  import { createAsciinemaPlayerController } from "@cofob/design-system-asciinema-player";

  const root = document.querySelector("[data-cf-asciinema-player]");
  const player = createAsciinemaPlayerController(root, {
    source: "/recordings/demo.cast",
    options: { cols: 100, fit: "width" },
    fallbackHref: "/recordings/demo",
    labels: { loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" },
    onPlayerReady: setPlayer,
    onPlayerLoadError: reportError,
  });
  window.addEventListener("pagehide", () => player.destroy(), { once: true });
</script>

Contract

CSS selector	`.cf-asciinema-player`
Adapters	Native · React · Svelte
Primary props	source · options · label · fallbackHref · labels · player · onPlayerReady · onPlayerLoadError · figure attributes
Documented states	SSR fallback · loading · ready · error · light · dark · reduced motion
Interaction	Shared controller or native behavior
Theme	Semantic light and dark tokens

Composition

Native attributes and framework props are forwarded. Add custom classes without replacing the semantic contract.

Parameters

Adapter differences are explicit. Native element attributes are forwarded in React and Svelte and can be written directly in HTML.

Parameter	Type	Default	Adapters	Example	Description
`source`required	`Source`	`required`	React · Svelte · HTML	`"/recordings/demo.cast"`	Recording URL, URL configuration, or in-memory recording data passed to asciinema-player.
`options`	`Options`	`{ theme: "cofob" } plus upstream defaults`	React · Svelte · HTML	`{{ cols: 100, fit: "width" }}`	Component-specific choices or configuration options.
`label`	`string`	`"Terminal recording"`	React · Svelte · HTML	`"Accessible label"`	Visible or accessible name, depending on the component.
`fallbackHref`	`string`	`—`	React · Svelte · HTML	`"/recordings/demo"`	Optional validated application route or direct recording link shown before mounting and on load failure.
`labels`	`Partial<AsciinemaPlayerLabels>`	`English loading, error, and link defaults`	React · Svelte · HTML	`{{ loadingTitle: "Terminal demo", errorTitle: "Player unavailable", fallbackLink: "Open recording" }}`	Localized visible and accessible labels.
`player`	`Player (bindable in Svelte)`	`undefined`	Svelte	`bind:player`	Exposes the current upstream imperative handle to Svelte and clears it during remount or disposal.
`onPlayerReady`	`(player: Player) => void`	`—`	React · Svelte · HTML	`{handlePlayerReady}`	Runs when the upstream UI is mounted; recording data may still be loading.
`onPlayerLoadError`	`(error: unknown) => void`	`—`	React · Svelte · HTML	`{handlePlayerLoadError}`	Runs when the player module cannot be imported or its UI cannot be created.
`figure attributes`	`native element attributes`	`—`	React · Svelte · HTML	`class / style / aria-* / data-*`	Forwards native class/style, accessibility, event, and data attributes to the root element.