Video
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.
<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.
- srcrequiredstring | Array<IVideoSource>
- Media URL or an array of IVideoSource descriptors (for multi-codec fallback). The browser picks the first decodable source.
- posterstring
- Image shown before playback starts. Maps to the native poster attribute (or is used as background in the #poster slot).
- tracksArray<IVideoTrack>[]
- Caption/subtitle/chapter tracks. Each entry maps to a <track> element with kind, src, srclang and label.
- autoplaybooleanfalse
- Starts playback after loadedmetadata. Automatically sets muted=true (browser requirement). Suppressed when prefers-reduced-motion: reduce is active.
- mutedbooleanfalse
- Starts the player muted. Required alongside autoplay for unattended playback.
- loopbooleanfalse
- Restarts playback when the video ends.
- Control surface: custom (in-house toolbar), native (browser controls) or none (consumer drives via #controls slot or exposed methods).
- playsInlinebooleantrue
- 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.
- aspectRatiostring'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.
- crossoriginTCrossOrigin
- CORS crossorigin attribute. Required when the media is from a different origin and canvas/WebAudio access is needed.
- disablePictureInPicturebooleanfalse
- Hides the PIP button and its keyboard shortcut.
- skipSecondsnumber30
- Seconds skipped by the ±skip buttons and double-tap gesture. Pass 0 to hide skip buttons.
- showCenterControlsbooleantrue
- Shows centered ±skip and play/pause overlay on hover and while paused.
- playbackRatesReadonlyArray<number>[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
- Available playback rates exposed in the settings menu.
- playbackRatenumber1
- Initial playback rate (1 = normal). Synced via update:playbackRate.
- insetbooleantrue
- When true, the controls toolbar is overlaid on the video bottom edge and auto-hides during playback.
- allowRemotePlaybackbooleantrue
- Shows the cast/AirPlay button when the browser exposes the Remote Playback API and a device is available.
- doubleTapToSkipbooleantrue
- Double-tap left half = skip backward, right half = skip forward on touch devices.
- downloadablebooleanfalse
- Adds a Download row in the settings menu. Uses a native anchor with download attribute — no XHR.
- downloadFilenamestring
- Override for the downloaded file name. Useful when the URL is opaque (e.g. signed S3 URL).
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- colorTColor
- bgColorTColor
- heightnumber | string
- Overrides the wrapper height (normally driven by aspect-ratio).
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- Overrides the wrapper width. Default is 100%.
- Border-radius token applied to the video wrapper.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- elevationTElevation
- Box-shadow elevation applied to the video wrapper.
- fontSizeTFontSize
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.
- @enterfullscreenvoid
- Fired when the player enters fullscreen.
- @exitfullscreenvoid
- Fired when the player exits fullscreen.
- @enterpipvoid
- Fired when picture-in-picture mode is entered.
- @exitpipvoid
- Fired when picture-in-picture mode is exited.
- @skipnumber
- Fired by skip buttons and double-tap gesture. Positive = forward, negative = backward (in seconds).
- @quality-changestring
- Fired when the viewer picks a different quality from the settings menu.
- @downloadstring
- Fired when the Download row is clicked. Payload is the file URL.
- @playvoid
- Fired when playback starts or resumes.
- @pausevoid
- Fired when playback is paused.
- @endedvoid
- Fired when the video reaches the end.
- @timeupdatenumber
- Fired periodically with the current playhead position in seconds.
- @volumechangenumber
- Fired when volume or muted state changes. Payload is the new volume (0–1).
- @loadedmetadata{ duration: number }
- @errorMediaError | Error
- @update:playbackRatenumber
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
Keyboard interactions
| Key | Action |
|---|---|
| Space / K | Toggle play/pause (when focus is on the player or controls). |
| ArrowRight / ArrowLeft | Seek forward/backward by 5 seconds. |
| ArrowUp / ArrowDown | Increase/decrease volume by 10%. |
| M | Toggle mute. |
| F | Toggle 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.
- colorvar(--origam-color---black)
- Wrapper background.
- dimensionvar(--origam-radius---md)
- Corner radius.
- colorvar(--origam-color__neutral---950)
- Controls bar background.
- colorvar(--origam-color__primary---500)
- Scrubber accent color.
- dimensionvar(--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
Autoplay muted loop
Custom controls slot