# Video player

A React component in [Beamline](https://beamline.io/)'s [Content & display](https://beamline.io/components/display) category. Live demo: https://beamline.io/components/video

A video player on the native <video> element: title bar with an external link and close, centre play with ±10 s, scrub, time, volume, speed, captions drawn in the system's type, picture-in-picture and fullscreen; full keyboard control, and loading, buffering, ended and error states.

## Use it for

- Product videos, walkthroughs and recordings inside an app or docs page.

## Not for

- Background or decorative video (a muted, looping <video> without controls).
- Live streams that need adaptive bitrate (use a streaming player with HLS or DASH and style it on tokens).

## Anatomy

- title bar (title, external link, close)
- centre controls (−10 s, play/pause, +10 s)
- captions
- control bar: play, scrub, time, volume, speed, captions, picture-in-picture, fullscreen
- buffering spinner
- error panel

## Variants

- **0**: hide: skip · volume · speed · captions · pip · fullscreen
- **1**: link (any external page)
- **2**: poster

## States

- loading (skeleton)
- paused
- playing (controls fade after 2.5 s of stillness; any movement, focus or key brings them back)
- buffering
- ended (replay)
- error (cannot play, with retry)
- muted
- captions on/off
- fullscreen
- picture-in-picture

## Keyboard

- Space or K: play/pause
- ← / →: 5 s back/forward; J / L: 10 s
- ↑ / ↓: volume
- M: mute
- C: captions
- F: fullscreen
- Home / End: start / end
- Keys work while focus is anywhere in the player except a slider, which keeps its own arrows

## Motion

Controls use the current motion tokens; managed/OS reduction settles decoration immediately. The 2.5-second idle timeout remains reading time.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src / poster` | `string` | — |  |
| `title` | `ReactNode` | — |  |
| `captions` | `VideoCaption[]` | — | { src, srcLang, label, default? } WebVTT tracks; C cycles through them and off. |
| `link` | `{ href, label }` | — | An external page for the video, opened in a new tab. |
| `onClose` | `() => void` | — | Shows a close button. |
| `label` | `string` | — | Accessible name; the title by default. |
| `autoPlay / muted / loop` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus the player on mount so its keys work at once. |
| `playing / onPlayingChange` | `boolean / (playing) => void` | — | Controlled play state. |
| `hide` | `("skip" \| "volume" \| "speed" \| "captions" \| "pip" \| "fullscreen")[]` | — |  |
| `loading` | `boolean` | — | A skeleton while the source is not known yet. |
| `className / videoClassName` | `string` | — |  |
| `crossOrigin` | `"anonymous" \| "use-credentials"` | — | Only for captions on another origin (that origin must send CORS headers). |
| `classNames` | `VideoPlayerClassNames` | — |  |
| `style / ref` | `CSSProperties / native Ref` | — |  |
| `videoRef / videoStyle` | `Ref<HTMLVideoElement> / CSSProperties` | — |  |

## Import

```tsx
import { VideoPlayer } from "@/components/video/video";
```

## Get it

Video player is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Content & display

- [Advertisement](https://beamline.io/components/advertisement): A sponsor or promo slot that turns through its ads on a hairline that fills; hovering or focusing holds the current ad.
- [Avatar](https://beamline.io/components/avatar): A person or account in a small space: a photo, or initials on the hue their name always gets; presence dot; circle for people, square for companies.
- [Avatar group](https://beamline.io/components/avatar-group): A team in a small space: overlapping faces that name themselves on hover or focus, and “+N” naming the rest.
- [Badge](https://beamline.io/components/badge): A short status, category or count label: six tones, an icon or a status dot, two sizes.
- [Code block](https://beamline.io/components/code-block): Code to read and copy: highlighted in the system's colours, numbered, marked lines, long files folded behind “Show all”.
- [Comment thread](https://beamline.io/components/comment-thread): A discussion attached to something: replies, reactions, @mentions, editing and deleting your own, resolve that folds the thread.
- [File diff](https://beamline.io/components/file-diff): A change to one file as a unified diff: line numbers, tinted lines, only the changed words marked, long unchanged stretches folded; give rows or just…
- [Image compare](https://beamline.io/components/image-compare): Two images in one frame with a divider: drag anywhere, or arrow keys on the handle; horizontal or vertical, with captions.
- [Item](https://beamline.io/components/item): The generic list row: media, title, description, meta and trailing actions; becomes a link or button when interactive.
- [Kbd](https://beamline.io/components/kbd): Keyboard keys as keycaps; `mod` resolves to ⌘ or Ctrl per platform, symbols are spoken as words.
- [Lightbox](https://beamline.io/components/lightbox): A full-screen image viewer: a thumbnail grows into it and shrinks back, arrows and ←/→ step through the set, Esc or a downward drag closes it.
- [Logo Carousel](https://beamline.io/components/logo-carousel): A wall of logos shown a few at a time: every few seconds the slots turn left to right, each logo leaving upward as the next rises in.
- [Marker](https://beamline.io/components/marker): A labelled point in a stream: a status event with an icon between messages, or a label such as "Today" between two hairlines.
- [QR Code](https://beamline.io/components/qr-code): A scannable code set as gradient dots with rounded finder rings and an optional centre mark; a new value ripples out from the centre.
- [Slot text](https://beamline.io/components/slot-text): Text and numbers that roll into their new value on reels, digit by digit from the right; other characters fade. Read as plain text by assistive tech.
- [Text morph](https://beamline.io/components/text-morph): A short label that becomes its next state letter by letter: shared letters glide into place, new ones arrive, old ones leave.
- [Text reveal](https://beamline.io/components/text-reveal): A headline whose words rise into place once, the first time it scrolls into view; never repeats.
- [Text shimmer](https://beamline.io/components/text-shimmer): Ongoing work said in words (“Thinking…”) with a calm band of light passing across them; stops when inactive.
- [Timeline](https://beamline.io/components/timeline): What happened, newest first and grouped by day: people with avatars, systems with toned icons, relative times with the exact time on hover, details in…