Video

Media
stable

Full-featured HTML5 video player with custom controls, picture-in-picture, fullscreen, captions, playback rate, cast/AirPlay and double-tap-to-skip. All browser native events are surfaced as Vue emits.

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamVideoSchematic of the Video player with 6 numbered internal parts. ▶ scrubber + time vol · pip · fs 1 2 3 4 5
Anatomy of <origam-video> — 5 internal parts. The wrapper ① positions the native <video> with its poster overlay ②; the controls bar ③ overlays the bottom edge and contains the scrubber ④ and action buttons ⑤.
1.origam-video
Root wrapper. position: relative, aspect-ratio enforced, border-radius from rounded prop.
2.origam-video__poster
Poster overlay rendered before playback starts. Hides on play. The #poster slot replaces it.
3.origam-video__controls
Control bar. Overlaid (inset=true, default) or always-visible (inset=false). The #controls slot replaces the entire bar.
4.origam-video__scrubber
Timeline scrubber — range input styled with CSS. Shows buffered region and playhead position.
5.origam-video__actions
Trailing action buttons: volume, PIP, fullscreen, captions, cast, settings.

API

Props

All props accepted by this component, with their type, default value and description.

src
required
string | Array<IVideoSource>
Media URL or an array of IVideoSource descriptors (for multi-codec fallback). The browser picks the first decodable source.
poster
string
Image shown before playback starts. Maps to the native poster attribute (or is used as background in the #poster slot).
tracks
Array<IVideoTrack>
[]
Caption/subtitle/chapter tracks. Each entry maps to a <track> element with kind, src, srclang and label.
autoplay
boolean
false
Starts playback after loadedmetadata. Automatically sets muted=true (browser requirement). Suppressed when prefers-reduced-motion: reduce is active.
muted
boolean
false
Starts the player muted. Required alongside autoplay for unattended playback.
loop
boolean
false
Restarts playback when the video ends.
controls
'custom'
Control surface: custom (in-house toolbar), native (browser controls) or none (consumer drives via #controls slot or exposed methods).
playsInline
boolean
true
Maps to the native playsinline attribute. Required on iOS to prevent the system hijacking playback.
preload
'none' | 'metadata' | 'auto'
'metadata'
Buffering hint. metadata loads just enough to compute duration; auto pre-buffers aggressively.
aspectRatio
string
'16/9'
CSS aspect-ratio applied to the wrapper. Prevents layout shift after metadata loads. Accepts presets (16/9, 4/3, 1/1, 21/9) or any raw value.
crossorigin
TCrossOrigin
CORS crossorigin attribute. Required when the media is from a different origin and canvas/WebAudio access is needed.
disablePictureInPicture
boolean
false
Hides the PIP button and its keyboard shortcut.
skipSeconds
number
30
Seconds skipped by the ±skip buttons and double-tap gesture. Pass 0 to hide skip buttons.
showCenterControls
boolean
true
Shows centered ±skip and play/pause overlay on hover and while paused.
playbackRates
ReadonlyArray<number>
[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
Available playback rates exposed in the settings menu.
playbackRate
number
1
Initial playback rate (1 = normal). Synced via update:playbackRate.
inset
boolean
true
When true, the controls toolbar is overlaid on the video bottom edge and auto-hides during playback.
allowRemotePlayback
boolean
true
Shows the cast/AirPlay button when the browser exposes the Remote Playback API and a device is available.
doubleTapToSkip
boolean
true
Double-tap left half = skip backward, right half = skip forward on touch devices.
downloadable
boolean
false
Adds a Download row in the settings menu. Uses a native anchor with download attribute — no XHR.
downloadFilename
string
Override for the downloaded file name. Useful when the URL is opaque (e.g. signed S3 URL).
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
color
TColor
bgColor
TColor
height
number | string
Overrides the wrapper height (normally driven by aspect-ratio).
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
Overrides the wrapper width. Default is 100%.
Border-radius token applied to the video wrapper.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
elevation
TElevation
Box-shadow elevation applied to the video wrapper.
fontSize
TFontSize

API

Slots

Content slots exposed by this component.

#controls
Full toolbar replacement. Receives the complete IVideoScopedSlotBindings state + imperative methods. The built-in toolbar uses the same surface.
#poster
Overlay rendered before playback starts (currentTime===0 && paused). When absent, the poster prop is used as a background-image on the video element.
#loading
Custom overlay rendered while the media is buffering.
#error
Custom overlay rendered when a media error occurred. Receives the error object.

API

Emits

Events emitted by this component.

@enterfullscreen
void
Fired when the player enters fullscreen.
@exitfullscreen
void
Fired when the player exits fullscreen.
@enterpip
void
Fired when picture-in-picture mode is entered.
@exitpip
void
Fired when picture-in-picture mode is exited.
@skip
number
Fired by skip buttons and double-tap gesture. Positive = forward, negative = backward (in seconds).
@quality-change
string
Fired when the viewer picks a different quality from the settings menu.
@download
string
Fired when the Download row is clicked. Payload is the file URL.
@play
void
Fired when playback starts or resumes.
@pause
void
Fired when playback is paused.
@ended
void
Fired when the video reaches the end.
@timeupdate
number
Fired periodically with the current playhead position in seconds.
@volumechange
number
Fired when volume or muted state changes. Payload is the new volume (0–1).
@loadedmetadata
{ duration: number }
@error
MediaError | Error
@update:playbackRate
number

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

Ref<HTMLVideoElement | null>
Direct reference to the underlying HTMLVideoElement. Use for advanced integrations (WebGL, WebAudio, canvas).
IVideoPlayerState
Reactive state object: playing, paused, currentTime, duration, buffered, volume, muted, fullscreen, pip, loading, error, playbackRate.
IVideoPlayerMethods
Imperative methods: play, pause, togglePlay, seek, setVolume, toggleMute, enterFullscreen, exitFullscreen, toggleFullscreen, requestPip, exitPip, togglePip.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Video wrapper background (black by default for letterboxing).
Corner radius of the video wrapper.
Controls bar background (very dark for legibility on any content).
Size of control buttons in the toolbar.
Accent color of the playhead/thumb on the scrubber.
Font size for the current-time / duration display.

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

region

Keyboard interactions

Keyboard interactions
KeyAction
Space / KToggle play/pause (when focus is on the player or controls).
ArrowRight / ArrowLeftSeek forward/backward by 5 seconds.
ArrowUp / ArrowDownIncrease/decrease volume by 10%.
MToggle mute.
FToggle fullscreen.

Notes

  • Subtitles/captions are provided via the tracks prop using WebVTT format. The captions button in the toolbar toggles the active track.
  • Autoplay is suppressed when prefers-reduced-motion: reduce is active, respecting the user preference.
  • The controls bar uses aria-label for icon-only buttons (play, mute, fullscreen). The scrubber is a range input with aria-label, aria-valuemin, aria-valuemax and aria-valuenow.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

Source
color
var(--origam-color---black)
Wrapper background.
dimension
var(--origam-radius---md)
Corner radius.
color
var(--origam-color__neutral---950)
Controls bar background.
color
var(--origam-color__primary---500)
Scrubber accent color.
dimension
var(--origam-space---16)
Size of the centered play button on the poster overlay.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic player

vue

Autoplay muted loop

vue

Custom controls slot

vue