Video
HTML5 video player with poster image, optional embedded iframe (YouTube, Vimeo), and an optional transcript revealed via a native <details> element. Classless by default on <video>; an opt-in .video class wraps iframe embeds in a responsive aspect-ratio container.
Usage
When to use
- Embedding a mission briefing, interview, or product demo
- Inline playback of a hosted
.mp4/.webmfile - Wrapping a third-party iframe (YouTube, Vimeo) at a consistent aspect ratio
When not to use
- Animated decoration - use a muted looping
<img>or CSS animation instead - Audio-only content - use an
<audio>element - Background hero video that isn't essential - consider a poster image for performance
Do
- Provide a poster image so the player has something to show before playback
- Always include captions via
<track>where possible - Provide a transcript for any video that conveys essential information
- Give every iframe embed a descriptive
title
Don't
- Autoplay with sound
- Omit captions on videos that carry spoken content
- Rely on color or on-screen text alone for critical information
API
Slots
| Slot | Required | Description |
|---|---|---|
transcript | - | Transcript content (HTML or text) revealed via the disclosure. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
sources | array | - | Array of {src, type} source objects for native video playback. |
poster | string | - | Poster image URL displayed before the video plays. |
tracks | array | - | Array of {src, kind, srclang, label} track objects for captions and subtitles. |
embed_url | string | - | Iframe embed URL for YouTube, Vimeo, or other platforms. |
embed_title | string | Embedded video | Accessible title for the iframe. |
transcript_label | string | Transcript | Summary label for the transcript toggle. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.cover | Fit | - | Content fills the box, cropping overflow (object-fit: cover). |
.contain | Fit | - | Content scales within the box preserving aspect ratio (object-fit: contain). |
.fill | Fit | - | Content stretches to fill the box, may distort (object-fit: fill). |
Examples
Native video
Classless <video> with poster, controls, and <source> children.
With captions
Native <video> with <track kind="captions"> WebVTT file.
With transcript
Video paired with a collapsible transcript in <details>.
YouTube embed
.video wrapper around a YouTube iframe with responsive aspect ratio.
Vimeo embed
.video wrapper around a Vimeo iframe.
Accessibility
- WCAG 2.2 AA
- Captions for any spoken content (WCAG 1.2.2)
- Transcript provides a text alternative for deaf/hard-of-hearing users and for users who prefer reading
- Iframe embeds have a descriptive
titleattribute - Player controls are keyboard accessible (native controls satisfy this for
<video>; third-party iframes inherit the provider's accessibility) - No autoplay with sound