VideoPlayer

A native video behind a poster and one large play button; the browser's own controls take over once it plays.

Last updated

Uses JavaScript

Shows the large play button over the poster and hides the browser’s controls until the first play, then hands over to them.

Without JS: The play button is hidden and the browser's own video controls show from the start.

Show code
<VideoPlayer src="/media/app-tour.mp4" poster="/mockups/app-desktop-light.jpg" captions="/media/app-tour.vtt" title="A tour of the dashboard" />

Add

npx @ava-ui/apogee add video-player

Uses @lucide/astro (Play).

Usage

---
import VideoPlayer from '@/components/apogee/VideoPlayer/VideoPlayer.astro'
---
<VideoPlayer src="/media/tour.mp4" poster="/media/tour.jpg" captions="/media/tour.vtt" title="A tour of the reports page" />

API

Prop Type Default Description
src string — The video file (MP4 or WebM).
title string — What the video shows; names the play button (“Play video: …”).
poster string — The image shown before it plays.
captions string — A WebVTT captions file, on by default.
captionsLang string 'en' Language of the captions.
ratio '16/9' | '16/10' | '4/3' | '1/1' '16/9' Reserves the space before the video loads.
radius 'none' | 'small' | 'medium' | 'large' | 'full' 'large' Corner rounding. full is the largest rounding a video takes without cropping the picture.
class string — Size it here (max-w-3xl, w-full).

Variants

Every ratio:

Show code
<VideoPlayer ratio="16/9" … />
<VideoPlayer ratio="16/10" … />
<VideoPlayer ratio="4/3" … />
<VideoPlayer ratio="1/1" … />

Every radius:

Show code
<VideoPlayer radius="none" … />
<VideoPlayer radius="small" … />
<VideoPlayer radius="medium" … />
<VideoPlayer radius="large" … />
<VideoPlayer radius="full" … />

States

  • Before play — the poster and the play button; the browser’s controls are hidden.
  • Playing — the button is gone and the browser’s controls take over: pause, seek, volume, captions, full screen.

Examples

Feature sections with a video: Features sections.

Accessibility

  • The play button is named “Play video: {title}”; after it, focus moves to the video, where the browser’s controls take the keyboard.
  • preload="none": nothing downloads until someone presses play.
  • Give the video captions (captions) when it has speech or text that matters.
  • The play button’s hover growth respects prefers-reduced-motion.

Tokens

Token Used for
--background-inverted Behind the video while it loads
--background-page Play button disc
--shadow-raised Lift
--duration-fast / ease-standard Play button hover

Do / Don’t

  • Do set a poster; without one the frame is a dark box until it plays.
  • Don’t autoplay with sound.

Content

  • Write title for what happens in the video (“A tour of the reports page”), not “Video”.

Related

DeviceFrameA screenshot in a phone, a landscape tablet or a browser window, drawn in CSS with the theme's colours; it scales as a whole and a dark screenshot swaps in with the theme.
ImageA responsive, lazy-loaded image — wraps astro:assets Image with sensible defaults.
AspectRatioLocks its content to a fixed width-to-height ratio — media, embeds, maps.