# VideoPlayer

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

URL: https://apogee.avaui.dev/docs/video-player
Last updated: 2026-10-16

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

Last updated October 16, 2026

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.

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

## Add

```sh
npx @ava-ui/apogee add video-player
```

Uses `@lucide/astro` (`Play`).

## Usage

```astro
---
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`:

```astro
<VideoPlayer ratio="16/9" … />
<VideoPlayer ratio="16/10" … />
<VideoPlayer ratio="4/3" … />
<VideoPlayer ratio="1/1" … />
```

Every `radius`:

```astro
<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](https://apogee.avaui.dev/docs/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.

](https://apogee.avaui.dev/docs/device-frame)[

ImageA responsive, lazy-loaded image — wraps astro:assets Image with sensible defaults.

](https://apogee.avaui.dev/docs/image)[

AspectRatioLocks its content to a fixed width-to-height ratio — media, embeds, maps.

](https://apogee.avaui.dev/docs/aspect-ratio)