@teletext/react

Embed ASCII art animations in any React app. One component, zero config.

Install

npm install @teletext/react

Usage

Export a .teletext file from teletext.com, drop it in your public/ directory, and point at it:

import { TeletextEmbed } from '@teletext/react'

<TeletextEmbed data="/animation.teletext" autoPlay loop />

Or pass raw bytes:

const bytes = new Uint8Array(await fetch('/animation.teletext').then(r => r.arrayBuffer()))
<TeletextEmbed data={bytes} autoPlay loop />

Examples

Full-screen background

<TeletextEmbed
  data="/bg.teletext"
  autoPlay
  loop
  backgroundColor="#000"
  style={{ position: 'fixed', inset: 0, opacity: 0.3, zIndex: -1 }}
/>

Hero section

<TeletextEmbed
  data="/animation.teletext"
  autoPlay
  loop
  fontFamily="'Fira Code', monospace"
  className="w-full h-[400px]"
/>

SSR-safe rendering

The dom renderer outputs <pre> and <span> elements — no canvas, works with SSR, accessible to screen readers.

<TeletextEmbed data="/animation.teletext" renderer="dom" autoPlay loop />

Pause / resume

const [paused, setPaused] = useState(false)

<TeletextEmbed data="/animation.teletext" autoPlay loop paused={paused} />
<button onClick={() => setPaused(p => !p)}>
  {paused ? 'Play' : 'Pause'}
</button>

Single frame (low-level)

import { TeletextCanvas, TeletextDom, loadTeletext } from '@teletext/react'

const data = await loadTeletext('/animation.teletext')
<TeletextCanvas frame={data.frames[0]} cellSize={12} />
<TeletextDom frame={data.frames[0]} />

API

<TeletextEmbed>

| Prop | Type | Default | | |------|------|---------|---| | data | Uint8Array \| string | required | Binary bytes or URL to .teletext file | | renderer | "canvas" \| "dom" | "canvas" | Canvas = fast. DOM = SSR + accessible. | | autoPlay | boolean | false | Play on mount | | loop | boolean | false | Loop the animation | | paused | boolean | false | External pause control | | fps | number | from export | Override frame rate | | fontFamily | string | "monospace" | Any monospace font | | backgroundColor | string | "#111" | Background color | | className | string | — | Wrapper CSS class | | style | CSSProperties | — | Wrapper inline styles | | aria-label | string | "ASCII art animation" | Accessibility label |

The canvas scales to fill its container. Animations automatically pause when off-screen via IntersectionObserver.

<TeletextCanvas>

Renders a single frame to <canvas>. Scales to fill its container.

| Prop | Type | Default | | |------|------|---------|---| | frame | TeletextFrame | required | Single frame to render | | cellSize | number | 10 | Character size in px | | fontFamily | string | "monospace" | Font | | backgroundColor | string | "#111" | Background |

Ref: getCanvas() returns the <canvas> element.

<TeletextDom>

Renders a single frame as <pre> + colored <span> elements.

| Prop | Type | Default | | |------|------|---------|---| | frame | TeletextFrame | required | Single frame to render | | fontFamily | string | "monospace" | Font | | backgroundColor | string | "#111" | Background |

Codec

Encode and decode .teletext binary files directly:

import { encode, decode, loadTeletext } from '@teletext/react'

// Decode from URL
const data = await loadTeletext('/animation.teletext')

// Decode from bytes
const data = await decode(bytes)

// Encode TeletextData to compressed binary
const bytes = await encode(data)

Utilities

For custom renderers or playback logic:

import { renderCanvasFrame, renderDomFrame, getFrameIndex } from '@teletext/react'

// Draw to any canvas context
renderCanvasFrame(ctx, frame, { cellSize: 10 })

// Get React elements
const elements = renderDomFrame(frame)

// Frame timing math
const index = getFrameIndex(elapsedMs, frameCount, fps, loop)

.teletext binary format

Compressed binary — each cell is 1 byte (space) or 4 bytes (char index + RGB), gzipped with browser-native CompressionStream. Typical compression results:

| Content | JSON | .teletext | Reduction | |---------|------|-------------|-----------| | 51x91, 85 frames | 13 MB | 201 KB | 98.5% | | 90x160, 85 frames | 43 MB | 1.6 MB | 96.3% |

Requirements

React 18+. No other dependencies.

License

MIT