Skip to main content

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/.webm file
  • 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​

SlotRequiredDescription
transcript-Transcript content (HTML or text) revealed via the disclosure.

Props​

PropTypeDefaultDescription
sourcesarray-Array of {src, type} source objects for native video playback.
posterstring-Poster image URL displayed before the video plays.
tracksarray-Array of {src, kind, srclang, label} track objects for captions and subtitles.
embed_urlstring-Iframe embed URL for YouTube, Vimeo, or other platforms.
embed_titlestringEmbedded videoAccessible title for the iframe.
transcript_labelstringTranscriptSummary label for the transcript toggle.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.coverFit-Content fills the box, cropping overflow (object-fit: cover).
.containFit-Content scales within the box preserving aspect ratio (object-fit: contain).
.fillFit-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 title attribute
  • Player controls are keyboard accessible (native controls satisfy this for <video>; third-party iframes inherit the provider's accessibility)
  • No autoplay with sound
  • figure - figure with caption wrapper
  • image - poster image source