` without one. Markers are decorative: the slider's own value is what assistive technology reads.
#### Data attributes
| Attribute | Description |
| --- | --- |
| `data-seeking` | Present when a seek operation is in progress. |
### media-slider-buffer
Displays the buffered range on the slider track.
### media-slider-fill
Displays the filled portion from start to the current value.
### media-slider-preview
Positioning container for preview content that tracks the pointer along the slider.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
### media-slider-thumb
Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
### media-slider-track
Contains the slider's visual track and interactive hit zone.
### media-slider-value
Writes the formatted current or pointer slider value into its own text content, replacing any children.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
---
# media-time-slider-markers
Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks
A part of the [time slider](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/time-slider) that draws a marker for each cue on the text tracks a filter matches, such as ad breaks, quiz questions, or highlights. Its props, data attributes, and custom properties are listed with the time slider’s other parts.
## Import
```ts
import '@videojs/html/ui/time-slider-markers';
```
## Anatomy
```html
```
Each marker is a `
`, or a clone of a `
` child. The template must contain exactly one HTML root element, and stays in the light DOM.
```html
```
## Behavior
The `kind`, `label`, and `language` attributes pick the tracks whose cues are drawn. The `filter` property takes a filter object, a function, or a [track definition](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/api/define-text-track) instead, and takes priority over the attributes. With neither, nothing is drawn.
Tracks from the media and from the app are drawn alike. While the markers are rendered, the [text cues feature](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/api/feature-text-cues) reads the tracks they match, so tracks it skips by default work too.
A cue whose end is its start is a point, drawn as a marker with no width and `data-point`. Any other cue is a range, spanning from its start to its end and clamped to the slider. Markers sit on the same span as the slider: from `0` to the media’s duration, or to the end of its seekable range while the duration is unknown. Cues outside that span, and every cue while it’s unknown, aren’t drawn. Markers are ordered by start, then end.
## Styling
| Attribute | Description |
| --- | --- |
| `data-active` | Present while the marker’s cue is active. |
| `data-point` | Present when the cue marks one moment rather than a span. |
Each marker also carries the slider’s data attributes, such as `data-orientation`, and its geometry through:
- `--media-slider-marker-start`
- `--media-slider-marker-end`
- `--media-slider-marker-width`, the marker’s size along the slider, `0%` for a point
Markers are unstyled. Position each one from its custom properties, and give points a visible width:
```css
media-time-slider-markers > div {
position: absolute;
inset-block: 0;
left: var(--media-slider-marker-start);
width: var(--media-slider-marker-width);
min-width: 4px;
}
media-time-slider-markers > [data-active] {
background: orange;
}
```
## Accessibility
The markers render with `aria-hidden="true"`; the slider’s value is what assistive technology reads. When a marker carries meaning a viewer needs, such as an upcoming ad break, convey it another way too.
## Examples
### Basic usage
An app track labeled `ads` holds a point at 8 seconds and a range from 18 to 24 seconds. A marker turns orange while its cue is active.
**index.html**
```html
```
**index.css**
```css
.html-time-slider-markers-basic__container {
position: relative;
}
.html-time-slider-markers-basic__container video {
width: 100%;
aspect-ratio: 16 / 9;
}
.html-time-slider-markers-basic__slider {
position: absolute;
right: 12px;
bottom: 12px;
left: 12px;
display: flex;
align-items: center;
height: 20px;
cursor: pointer;
}
.html-time-slider-markers-basic__track,
.html-time-slider-markers-basic__markers {
position: absolute;
right: 0;
left: 0;
height: 4px;
}
.html-time-slider-markers-basic__track {
overflow: hidden;
background: rgba(255, 255, 255, 0.3);
border-radius: 9999px;
}
.html-time-slider-markers-basic__fill {
position: absolute;
inset-block: 0;
left: 0;
width: var(--media-slider-fill);
background: white;
}
.html-time-slider-markers-basic__marker {
position: absolute;
inset-block: 0;
left: var(--media-slider-marker-start);
width: var(--media-slider-marker-width);
min-width: 4px;
background: #facc15;
}
.html-time-slider-markers-basic__marker[data-point] {
transform: translateX(-50%);
}
.html-time-slider-markers-basic__marker[data-active] {
background: #f97316;
}
.html-time-slider-markers-basic__thumb {
position: absolute;
left: var(--media-slider-fill);
width: 12px;
height: 12px;
background: white;
border-radius: 50%;
transform: translateX(-50%);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/time-slider-markers';
const player = document.querySelector('video-player');
player?.store.addTextTrack({
kind: 'metadata',
label: 'ads',
cues: [{ startTime: 8 }, { startTime: 18, endTime: 24 }],
});
```
---
# media-volume-slider
A slider component for controlling media playback volume
## Import
```ts
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/slider-value';
```
## Anatomy
```html
```
## Behavior
Controls the media volume level. The slider maps its 0–100 internal range to the media’s 0–1 volume scale. When the media is muted, the fill level drops to 0 regardless of the stored volume value.
When `volumeAvailability` is not `"available"`, the element receives native `hidden`, `data-hidden`, and disabled ARIA semantics. This is independent of `mutedAvailability`, which controls whether the mute button is shown.
## Styling
Use [CSS custom properties](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/volume-slider#root-css-custom-properties) to style the fill and pointer levels:
```css
media-volume-slider::before {
width: var(--media-slider-fill);
}
```
## Accessibility
Renders with `role="slider"` and an automatic `aria-label` that resolves to “Volume” from the active locale. Override with the `label` prop. Keyboard controls:
- Arrow Left / Arrow Right: step by `step` increment
- Page Up / Page Down: step by `largeStep` increment
- Home: set volume to 0
- End: set volume to max
Before each keyboard step, the volume snaps to the nearest multiple of `step`.
Scroll wheel support:
- **Mouse wheel / trackpad scroll**: adjusts volume by `wheelStep` increment (default `5`)
## Examples
Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, draggable thumb, and a tooltip that shows the volume percentage on hover.
**index.html**
```html
Unmute
Mute
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-player media-container video {
width: 100%;
}
.media-mute-button {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.media-mute-button .muted {
display: none;
}
.media-mute-button .unmuted {
display: none;
}
.media-mute-button[data-muted] .muted {
display: inline;
}
.media-mute-button:not([data-muted]) .unmuted {
display: inline;
}
.media-volume-slider {
position: absolute;
right: 10px;
bottom: 10px;
display: flex;
align-items: center;
width: 100px;
height: 20px;
cursor: pointer;
}
.media-slider-track {
position: absolute;
right: 0;
left: 0;
height: 4px;
background: rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
transition: height 150ms ease;
}
.media-volume-slider[data-interactive] .media-slider-track {
height: 6px;
}
.media-slider-fill {
position: absolute;
top: 0;
left: 0;
width: var(--media-slider-fill);
height: 100%;
background: white;
border-radius: 9999px;
}
.media-slider-thumb {
position: absolute;
left: var(--media-slider-fill);
width: 14px;
height: 14px;
background: white;
border-radius: 50%;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
transform: translateX(-50%) scale(0);
transition: transform 150ms ease;
}
.media-volume-slider[data-interactive] .media-slider-thumb {
transform: translateX(-50%) scale(1);
}
.media-volume-slider[data-dragging] .media-slider-thumb {
transform: translateX(-50%) scale(1.1);
}
.media-slider-value {
position: absolute;
bottom: 100%;
left: var(--media-slider-pointer);
padding: 2px 6px;
margin-bottom: 6px;
font-size: 12px;
color: white;
white-space: nowrap;
pointer-events: none;
background: rgba(0, 0, 0, 0.8);
border-radius: 4px;
opacity: 0;
transform: translateX(-50%);
transition: opacity 150ms ease;
}
.media-volume-slider[data-pointing] .media-slider-value {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-value';
```
## API Reference
### media-volume-slider
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the slider is non-interactive. |
| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
| `largeStep` (attribute `large-step`) | `number` | `10` | Large step increment (Page Up/Down keys). |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of slider movement. |
| `step` | `number` | `5` | Step increment for value changes (arrow keys). |
| `thumbAlignment` (attribute `thumb-alignment`) | `'center' \| 'edge'` | `'center'` | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
| `wheelStep` (attribute `wheel-step`) | `number` | `5` | Step increment for wheel scrolling. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `value` | `number` | Current slider value in the min–max range. |
| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
| `dragging` | `boolean` | Whether the user is actively dragging. |
| `pointing` | `boolean` | Whether the pointer is over the slider. |
| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
| `disabled` | `boolean` | Whether the slider is non-interactive. |
| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |
| `volume` | `number` | Volume level from 0 (silent) to 1 (max). |
| `muted` | `boolean` | Whether audio is muted. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | |
| `hidden` | `boolean` | |
#### Data attributes
| Attribute | Type |
| --- | --- |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` |
| `data-hidden` | — |
#### CSS custom properties
| Variable | Description |
| --- | --- |
| `--media-slider-fill` | Fill level percentage (0–100), representing the current volume level. |
| `--media-slider-pointer` | Pointer position percentage (0–100), tracking the cursor along the slider. |
#### Events
| Event | Description |
| --- | --- |
| `drag-end` | Fired when a pointer drag ends. |
| `drag-start` | Fired when a pointer drag starts. |
### media-slider-fill
Displays the filled portion from start to the current value.
### media-slider-preview
Positioning container for preview content that tracks the pointer along the slider.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
### media-slider-thumb
Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
### media-slider-track
Contains the slider's visual track and interactive hit zone.
### media-slider-value
Writes the formatted current or pointer slider value into its own text content, replacing any children.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |
---
# media-menu
A composable menu component for settings, option selection, and actions
## Import
```ts
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-item';
import '@videojs/html/ui/menu-group';
import '@videojs/html/ui/menu-group-label';
import '@videojs/html/ui/menu-separator';
import '@videojs/html/ui/menu-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-checkbox-item';
import '@videojs/html/ui/menu-item-indicator';
```
## Anatomy
`` is the root menu and its one positioned popup. The root and nested `` elements are its direct children and share that popup.
```html
Settings
```
## Behavior
Menus open from a trigger and close when you select an item, click outside, move focus away, or press Escape. Root menus use `side` and `align` as their preferred placement. When the preferred side overflows the positioning boundary, the menu uses the opposite side if it has more space.
Root menus inside a [player container](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/player-container) join its popup group. Opening one closes any other root menu or popover that is open in the same container. Submenus remain part of their root menu instead of registering separately.
To create a submenu, add another `` as a sibling, give it an `id`, and point the parent `` at it with `commandfor`.
Media option groups share their option state with the enclosing menu: the selected value, and whether the options are disabled, hidden, or available. The menu’s trigger inherits the disabled and hidden state and exposes `data-availability`, and the menu closes if its options disappear while open. See [PlaybackRateRadioGroup](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/playback-rate-radio-group), [QualityRadioGroup](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/quality-radio-group), [AudioTrackRadioGroup](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/audio-track-radio-group), and [CaptionsRadioGroup](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/captions-radio-group).
The generated radio group publishes its state to the `` that contains it. Add an element with `data-part="hint"` inside the parent `` and the menu writes the selected label into it:
```html
Quality
```
## Styling
Use data attributes to style open state, highlighted items, selected radio items, and submenu views:
`data-highlighted` identifies the current menu item. Its value is `"pointer"` when pointer movement caused the highlight and an empty string for other highlights, including keyboard navigation and type-ahead search. Use `[data-highlighted]` to match any highlighted item or `[data-highlighted=""]` to match highlights that were not caused by pointer movement.
The root `` receives `data-open`, `data-side`, and `data-align`. Each `` receives menu state such as `data-open` and `data-submenu`; a content element with an open logical child receives `data-child-open`.
Every navigable item receives `data-item`. Use `[data-item]` when one rule should target regular, radio, checkbox, and submenu-trigger items together.
```css
media-menu[data-open] {
opacity: 1;
}
media-menu-content[data-child-open] {
translate: -100% 0;
}
media-menu-item[data-highlighted] {
background: rgba(255, 255, 255, 0.16);
transition: background-color 100ms ease-in-out;
}
media-menu-item[data-highlighted=""] {
transition-duration: 0ms;
}
media-menu-radio-item[aria-checked="true"] {
font-weight: 600;
}
```
## Accessibility
Menu content renders with `role="menu"`. Items use `menuitem`, `menuitemradio`, or `menuitemcheckbox` roles. Radio and checkbox items reflect selection with `aria-checked`.
Keyboard controls:
- Enter / Space: Select the highlighted item.
- Arrow Up / Arrow Down: Move between items.
- Arrow Right: Open a submenu.
- Arrow Left: Return to the parent menu.
- Escape: Close the root menu or return from a submenu.
Use `` inside grouped choices so the group receives an accessible label.
## Examples
### Basic usage
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-media {
width: 100%;
}
.menu-bar {
position: absolute;
right: 10px;
bottom: 10px;
}
.settings-trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.35);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.menu {
--media-menu-side-offset: 8px;
--menu-transition-duration: 220ms;
position: relative;
box-sizing: border-box;
width: var(--media-menu-width);
min-width: 180px;
max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
height: var(--media-menu-height);
max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
padding: 6px;
overflow: hidden;
overscroll-behavior: none;
font-size: 14px;
color: white;
background: rgba(0, 0, 0, 0.88);
border-radius: 8px;
backdrop-filter: blur(10px);
transition-timing-function: ease-in-out;
transition-duration: var(--menu-transition-duration);
transition-property: width, height, opacity, filter;
}
.menu-content,
.menu-panel {
position: absolute;
inset: 0;
display: grid;
gap: 2px;
padding: 6px;
overflow: auto;
overscroll-behavior: none;
outline: none;
translate: 0 0;
transition-timing-function: ease-in-out;
transition-duration: var(--menu-transition-duration);
transition-property: translate, filter;
}
.menu-content[data-child-open] {
filter: blur(8px);
translate: -100% 0;
}
.menu-panel[data-submenu] {
z-index: 1;
}
.menu-panel[data-submenu][data-starting-style],
.menu-panel[data-submenu][data-ending-style] {
overflow: hidden;
pointer-events: none;
filter: blur(8px);
translate: 100% 0;
}
.menu-item,
.menu-back {
display: flex;
align-items: center;
justify-content: space-between;
min-height: 32px;
padding: 0 10px;
font: inherit;
color: inherit;
cursor: pointer;
background: none;
border: 0;
border-radius: 6px;
}
.menu-item[data-highlighted],
.menu-back:hover {
background: rgba(255, 255, 255, 0.16);
}
.menu-back {
gap: 8px;
justify-content: flex-start;
}
.menu-item[data-availability="unavailable"] {
display: none;
}
.menu-value {
display: inline-flex;
gap: 8px;
align-items: center;
color: rgba(255, 255, 255, 0.72);
}
.menu-value [aria-hidden] {
font-size: 18px;
line-height: 1;
}
.menu-back [aria-hidden] {
font-size: 18px;
line-height: 1;
color: rgba(255, 255, 255, 0.72);
}
.menu-group {
display: grid;
gap: 2px;
}
.menu-tier {
margin-left: 2px;
font-size: 10px;
}
.menu-badge {
margin-left: auto;
color: rgba(255, 255, 255, 0.72);
}
.menu-indicator {
opacity: 0;
}
media-menu-radio-item[aria-checked="true"] .menu-indicator {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-item';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/quality-radio-group';
import '@videojs/html/ui/audio-track-radio-group';
import '@videojs/html/ui/playback-rate-radio-group';
import '@videojs/html/ui/captions-radio-group';
```
## API Reference
### media-menu
Root menu state and positioned popup. Content pages are direct children.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment along the trigger's edge. Root menus only. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the root menu popup. |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Close the menu when Escape is pressed at root level. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the menu when clicking outside. Root menus only. |
| `defaultOpen` (attribute `default-open`) | `boolean` | `false` | Initial open state (uncontrolled). |
| `open` | `boolean` | `false` | Controlled open state. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Preferred side of the trigger for the menu. Root menus only. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right' \| undefined` | Preferred side of the trigger for the menu. Root menus only. |
| `align` | `'start' \| 'center' \| 'end' \| undefined` | |
| `isSubmenu` | `boolean` | Whether this menu is nested inside another menu's content. |
#### CSS custom properties
| Variable | Description |
| --- | --- |
| `--media-popover-side-offset` | Distance between the popup and the trigger along the side axis. |
| `--media-popover-align-offset` | Distance between the popup and the trigger along the alignment axis. |
| `--media-popover-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
| `--media-popover-anchor-width` | Width of the trigger, set by popup positioning. |
| `--media-popover-anchor-height` | Height of the trigger, set by popup positioning. |
| `--media-menu-width` | Width of the active menu panel (px). |
| `--media-menu-height` | Height of the active menu panel (px). |
| `--media-menu-available-width` | Width available within the positioning boundary (px). |
| `--media-menu-available-height` | Height available within the positioning boundary (px). |
#### Events
| Event | Description |
| --- | --- |
| `open-change` | Fired before the menu's open state changes. Cancel the event to prevent the change. |
### media-menu-checkbox-item
Menu item that toggles `checked` when activated and leaves the menu open. The element itself takes `role="menuitemcheckbox"`.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the item is currently checked. |
| `disabled` | `boolean` | — | Whether the item is disabled. |
#### Data attributes
| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
#### Events
| Event | Description |
| --- | --- |
| `checked-change` | Fired when the checked state changes. |
### media-menu-content
One accessible menu page. Root and nested pages are sibling children of ``.
#### Events
| Event | Description |
| --- | --- |
| `open-change` | |
### media-menu-group
Groups related menu items; the element itself takes `role="group"`. A `` child names the group unless it already has an `aria-label` or `aria-labelledby`.
### media-menu-group-label
Non-interactive label that names its enclosing `` or ``.
### media-menu-item
Menu action; the element itself takes `role="menuitem"`. Activation fires a cancelable `select` event and then closes the menu, unless `commandfor` names a nested `` page to open instead.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Whether the item is disabled. |
#### Data attributes
| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
### media-menu-item-indicator
Decorative checked-state mark inside a menu item, hidden from assistive technology. It stays `hidden` unless `checked` or `force-mount` is set; option radio groups set `checked` on the indicators in the items they generate.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the indicator is currently shown. Typically bound to the parent item's checked state. |
| `forceMount` (attribute `force-mount`) | `boolean` | — | When `true`, renders even when unchecked (useful for animating out). Defaults to `false`. |
### media-menu-radio-group
Group of mutually exclusive `` children; the element itself takes `role="group"`.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | The currently selected value. |
#### Events
| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |
### media-menu-radio-item
Menu item that selects its `value` in the enclosing `` and closes the menu. The element itself takes `role="menuitemradio"`, checked while its value matches the group's.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Whether the item is disabled. |
| `value` | `string` | — | The value this item represents. |
#### Data attributes
| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
### media-menu-separator
Visual divider between groups of menu items; the element itself takes `role="separator"`.
---
# media-popover
A popover component for displaying contextual content anchored to a trigger
## Import
```ts
import '@videojs/html/ui/popover';
```
## Anatomy
```html
Open
Content
```
## Behavior
Displays contextual content anchored to a trigger element. By default, opens on click and closes when clicking outside, pressing Escape, or when the trigger loses focus.
Set `openOnHover` to open on pointer hover instead of click. Use `delay` and `closeDelay` to control timing for hover interactions.
Popovers inside a [player container](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/player-container) join its popup group. Opening one closes any other popover or root menu that is open in the same container. A popover outside the container still opens and closes normally, but it is not coordinated with that group.
The `side` and `align` props control the preferred popup placement relative to the trigger. When the preferred side overflows the positioning boundary, the popup uses the opposite side if it has more space.
`` is the popup. A trigger links to it through `commandfor` set to the popup’s `id`. If the popup has no `id`, it uses the element immediately before it as the trigger. It gives the popup a generated `id` and sets the trigger’s `commandfor` to that value. That element must not already target another popup through `commandfor`.
## Styling
Use [CSS custom properties](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/popover#root-css-custom-properties) for positioning offsets:
```css
media-popover {
--media-popover-side-offset: 8px;
--media-popover-align-offset: 0px;
--media-popover-boundary-offset: 8px;
}
```
Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:
```css
media-popover[data-open] {
display: block;
}
media-popover[data-starting-style] {
opacity: 0;
}
media-popover[data-ending-style] {
opacity: 0;
}
media-popover[data-side="top"] {
transform-origin: bottom center;
}
media-popover[data-side="bottom"] {
transform-origin: top center;
}
```
## Accessibility
The trigger receives `aria-expanded` reflecting the open state. When `modal` is set, the popup receives `aria-modal="true"`. Closing via Escape is enabled by default and can be disabled with `closeOnEscape={false}`.
## Examples
### Basic Usage
**index.html**
```html
Settings
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-player media-container video {
width: 100%;
}
.bar {
position: absolute;
bottom: 10px;
left: 10px;
}
.trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.media-popover {
padding: 12px 16px;
font-size: 14px;
color: white;
white-space: nowrap;
background: rgba(0, 0, 0, 0.85);
border-radius: 8px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/popover';
```
## API Reference
### media-popover
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the popup along the trigger's edge. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the popup position. |
| `closeDelay` (attribute `close-delay`) | `number` | `0` | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` (attribute `default-open`) | `boolean` | `false` | Initial open state for uncontrolled usage. |
| `delay` | `number` | `300` | Delay in ms before opening on hover. |
| `modal` | `boolean \| 'trap-focus'` | `false` | - `false` (default): non-modal; background content remains interactive. - `true`: modal; sets `aria-modal="true"` on the popup. - `'trap-focus'`: reserved for future focus-trapping behavior. |
| `open` | `boolean` | `false` | Controlled open state. When set, the consumer is responsible for toggling. |
| `openOnHover` (attribute `open-on-hover`) | `boolean` | `false` | Open the popup on pointer hover instead of click. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the popup. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the popup. |
| `align` | `'start' \| 'center' \| 'end'` | |
| `modal` | `boolean \| 'trap-focus'` | |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the popover after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popover is aligned relative to the specified side. |
#### CSS custom properties
| Variable | Description |
| --- | --- |
| `--media-popover-side-offset` | Distance between the popup and the trigger along the side axis. |
| `--media-popover-align-offset` | Distance between the popup and the trigger along the alignment axis. |
| `--media-popover-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
| `--media-popover-anchor-width` | The anchor element's width. |
| `--media-popover-anchor-height` | The anchor element's height. |
| `--media-popover-available-width` | Available width between the trigger and the boundary edge. |
| `--media-popover-available-height` | Available height between the trigger and the boundary edge. |
#### Events
| Event | Description |
| --- | --- |
| `open-change` | Fired when the popover's open state changes. |
---
# media-volume-popover
A volume-aware popover that keeps mute available when volume level controls are unavailable
## Import
```ts
import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
```
## Anatomy
```html
```
## Behavior
`` combines [popover behavior](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/components/popover) with volume availability. When volume level controls are unavailable, it closes and omits the popup while keeping the mute trigger rendered. This lets media with fixed volume keep mute control without exposing a nonfunctional slider.
The trigger can target the popup with `commandfor`. An immediately adjacent trigger is linked automatically when neither element has an authored ID.
## Styling
The popup reflects `data-availability="available"` while it can render volume controls.
When it cannot, the element also receives native `hidden` and `data-hidden`.
```css
media-volume-popover[data-open] {
opacity: 1;
}
```
## Accessibility
The trigger receives `aria-haspopup`, `aria-expanded`, and `aria-controls` while the volume popup is available. When only mute is available, the trigger keeps the mute button’s own accessible name and behavior without popup ARIA.
## Examples
### Basic usage
**index.html**
```html
Unmute
Mute
```
**index.css**
```css
.html-volume-popover-basic media-container {
position: relative;
display: block;
}
.html-volume-popover-basic video {
width: 100%;
}
.html-volume-popover-basic__controls {
position: absolute;
bottom: 10px;
left: 10px;
}
.html-volume-popover-basic__trigger {
padding: 8px 20px;
color: black;
cursor: pointer;
background: rgb(255 255 255 / 70%);
border: 1px solid rgb(255 255 255 / 30%);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.html-volume-popover-basic__trigger .muted,
.html-volume-popover-basic__trigger .unmuted {
display: none;
}
.html-volume-popover-basic__trigger[data-muted] .muted,
.html-volume-popover-basic__trigger:not([data-muted]) .unmuted {
display: inline;
}
.html-volume-popover-basic__popup {
--media-popover-side-offset: 8px;
width: 40px;
height: 120px;
padding: 12px;
margin: 0;
background: rgb(0 0 0 / 85%);
border: 0;
border-radius: 8px;
}
.html-volume-popover-basic__slider {
position: relative;
display: block;
width: 16px;
height: 96px;
margin: auto;
cursor: pointer;
}
.html-volume-popover-basic__track {
position: absolute;
top: 0;
bottom: 0;
left: 6px;
width: 4px;
background: rgb(255 255 255 / 30%);
border-radius: 9999px;
}
.html-volume-popover-basic__fill {
position: absolute;
right: 0;
bottom: 0;
left: 0;
height: var(--media-slider-fill);
background: white;
border-radius: inherit;
}
.html-volume-popover-basic__thumb {
position: absolute;
bottom: var(--media-slider-fill);
left: 1px;
width: 14px;
height: 14px;
background: white;
border-radius: 50%;
transform: translateY(50%);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
```
## API Reference
### media-volume-popover
A volume-aware popover that keeps its adjacent mute trigger available as a fallback.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | — | Alignment of the popup along the trigger's edge. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the popup position. |
| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | — | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | — | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` (attribute `default-open`) | `boolean` | — | Initial open state for uncontrolled usage. |
| `delay` | `number` | — | Delay in ms before opening on hover. |
| `modal` | `boolean \| 'trap-focus'` | — | - `false` (default): non-modal; background content remains interactive. - `true`: modal; sets `aria-modal="true"` on the popup. - `'trap-focus'`: reserved for future focus-trapping behavior. |
| `open` | `boolean` | — | Controlled open state. When set, the consumer is responsible for toggling. |
| `openOnHover` (attribute `open-on-hover`) | `boolean` | — | Open the popup on pointer hover instead of click. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | — | Preferred side of the trigger for the popup. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the popup. |
| `align` | `'start' \| 'center' \| 'end'` | |
| `modal` | `boolean \| 'trap-focus'` | |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether volume level controls are available. |
| `hidden` | `boolean` | Whether the popup is hidden because volume level controls are unavailable. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popup is aligned relative to its side. |
| `data-starting-style` | — | Present during the open transition. |
| `data-ending-style` | — | Present during the close transition. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates volume control availability (`available`, `unavailable`, or `unsupported`). |
| `data-hidden` | — | Present when volume level controls are unavailable. |
#### Events
| Event | Description |
| --- | --- |
| `open-change` | Fired when the popover's open state changes. |
---
# media-audio-track-radio-group
A menu radio group for selecting an audio track
Creates radio items from the player audio track state and selects the enabled track.
## Import
```ts
import '@videojs/html/ui/audio-track-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```
## Anatomy
```html
```
## Behavior
The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
`` generates `` children. Add an optional `` with a single `` to customize each generated item.
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-audio-track` | `string` | Current audio track value. |
| `data-disabled` | Present / absent | Present when audio track selection is disabled. |
| `data-hidden` | Present / absent | Present when multiple audio tracks are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether multiple audio tracks are available. |
Unavailable groups receive the native `hidden` attribute.
## Accessibility
The group uses the menu radio group pattern.
The element receives an accessible label from the `label` property or defaults to `Audio`.
## Examples
### Basic usage
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-media {
width: 100%;
}
.menu-bar {
position: absolute;
right: 10px;
bottom: 10px;
}
.menu-bar:has([data-availability="unavailable"]) {
display: none;
}
.settings-trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.35);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.menu {
--media-menu-side-offset: 8px;
box-sizing: border-box;
min-width: 180px;
max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
padding: 6px;
overflow: auto;
overscroll-behavior: none;
font-size: 14px;
color: white;
background: rgba(0, 0, 0, 0.88);
border-radius: 8px;
backdrop-filter: blur(10px);
}
.menu-group {
display: grid;
gap: 2px;
}
.menu-item {
display: flex;
gap: 8px;
align-items: center;
justify-content: space-between;
min-height: 32px;
padding: 0 10px;
font: inherit;
color: inherit;
cursor: pointer;
background: none;
border: 0;
border-radius: 6px;
}
.menu-item[data-highlighted] {
background: rgba(255, 255, 255, 0.16);
}
.menu-indicator {
opacity: 0;
}
media-menu-radio-item[aria-checked="true"] .menu-indicator {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/audio-track-radio-group';
```
## API Reference
### media-audio-track-radio-group
Menu radio group that generates a `` per available audio track and shares the selected label and availability with an enclosing menu. An optional `` holding one `` customizes each generated item.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether audio track selection is disabled. |
| `formatTrack` (attribute `format-track`) | `((track: MediaAudioTrack) => Text \| string)` | `formatTrackLabel` | Custom formatter for visible track labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: AudioTrackRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media exposes a meaningful selection. `unsupported` when the media has no such capability at all. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-audio-track` | `string` | Current audio track value. |
| `data-disabled` | — | Present when audio track selection is disabled. |
| `data-hidden` | — | Present when audio track selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates audio track availability (`available` or `unavailable`). |
#### Events
| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |
---
# media-captions-radio-group
A menu radio group for selecting caption and subtitle tracks
Creates radio items from the player text track state and selects the showing caption or subtitle track.
## Import
```ts
import '@videojs/html/ui/captions-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```
## Anatomy
```html
```
## Behavior
The group is available when the configured media exposes at least one caption or subtitle track. The first generated option is `Off`; selecting it hides captions. Track labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
`` generates `` children, including the `Off` item. Add an optional `` with a single `` to customize each generated item.
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-active` | Present / absent | Present when captions are enabled. |
| `data-disabled` | Present / absent | Present when track selection is disabled. |
| `data-hidden` | Present / absent | Present when caption or subtitle tracks are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether caption or subtitle tracks are available. |
Unavailable groups receive the native `hidden` attribute.
## Accessibility
The group uses the menu radio group pattern.
The element receives an accessible label from the `label` property or defaults to `Captions`.
## Examples
### Basic usage
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-player media-container video {
width: 100%;
}
.menu-bar {
position: absolute;
right: 10px;
bottom: 10px;
}
.settings-trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.35);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.menu {
--media-menu-side-offset: 8px;
box-sizing: border-box;
display: grid;
gap: 2px;
min-width: 180px;
max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
padding: 6px;
overflow: auto;
overscroll-behavior: none;
font-size: 14px;
color: white;
background: rgba(0, 0, 0, 0.88);
border-radius: 8px;
backdrop-filter: blur(10px);
}
.menu-group {
display: grid;
gap: 2px;
}
.menu-item {
display: flex;
gap: 8px;
align-items: center;
justify-content: space-between;
min-height: 32px;
padding: 0 10px;
font: inherit;
color: inherit;
cursor: pointer;
background: none;
border: 0;
border-radius: 6px;
}
.menu-item[data-highlighted] {
background: rgba(255, 255, 255, 0.16);
}
.menu-indicator {
opacity: 0;
}
media-menu-radio-item[aria-checked="true"] .menu-indicator {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/captions-radio-group';
```
## API Reference
### media-captions-radio-group
Menu radio group that generates an Off `` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `` holding one `` customizes each generated item; its `data-part` `label` and `badge` descendants receive the track's text.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether track selection is disabled. |
| `formatTrack` (attribute `format-track`) | `((track: MediaTextTrack) => Text \| string)` | `formatTrackLabel` | Custom formatter for visible track labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: CaptionsRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media exposes a meaningful selection. `unsupported` when the media has no such capability at all. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-active` | — | Present when captions are enabled. |
| `data-disabled` | — | Present when track selection is disabled. |
| `data-hidden` | — | Present when track selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates captions availability (`available` or `unavailable`). |
#### Events
| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |
---
# media-playback-rate-radio-group
A menu radio group for selecting playback speed
Creates radio items from the player playback rate state and selects the playback speed.
## Import
```ts
import '@videojs/html/ui/playback-rate-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```
## Anatomy
```html
```
## Behavior
The group is available when the configured media exposes playback rates. It offers the player’s playback rates, or its own when you set `rates`. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
When the current rate isn’t one the group offers, such as `1.1` set through the media API, the group adds it as an extra item before the next faster rate. That item carries `data-custom`, and its accessible name is “Custom, 1.1×” while its visible label stays `1.1×`. It goes away once the rate is back on the list.
`` generates `` children. Add an optional `` with a single `` to customize each generated item.
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-rate` | `number` | Current playback rate. |
| `data-disabled` | Present / absent | Present when playback rate selection is disabled. |
| `data-hidden` | Present / absent | Present when playback-rate selection is unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether playback rates are available. |
Unavailable groups receive the native `hidden` attribute. Each item carries `data-rate`, and an item for a current rate the group doesn’t offer also carries `data-custom`.
## Accessibility
The group uses the menu radio group pattern.
The element receives an accessible label from the `label` property or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby`.
## Examples
### Basic usage
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-player media-container video {
width: 100%;
}
.menu-bar {
position: absolute;
right: 10px;
bottom: 10px;
}
.settings-trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.35);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.menu {
--media-menu-side-offset: 8px;
box-sizing: border-box;
display: grid;
gap: 2px;
min-width: 180px;
max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
padding: 6px;
overflow: auto;
overscroll-behavior: none;
font-size: 14px;
color: white;
background: rgba(0, 0, 0, 0.88);
border-radius: 8px;
backdrop-filter: blur(10px);
}
.menu-group {
display: grid;
gap: 2px;
}
.menu-item {
display: flex;
gap: 8px;
align-items: center;
justify-content: space-between;
min-height: 32px;
padding: 0 10px;
font: inherit;
color: inherit;
cursor: pointer;
background: none;
border: 0;
border-radius: 6px;
}
.menu-item[data-highlighted] {
background: rgba(255, 255, 255, 0.16);
}
.menu-indicator {
opacity: 0;
}
media-menu-radio-item[aria-checked="true"] .menu-indicator {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/playback-rate-radio-group';
```
## API Reference
### media-playback-rate-radio-group
Menu radio group that generates a `` per available playback rate and shares the selected label and availability with an enclosing menu. An optional `` holding one `` customizes each generated item.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether playback rate selection is disabled. |
| `formatRate` (attribute `format-rate`) | `((rate: number) => string)` | `formatPlaybackRate` | Custom formatter for visible playback rate labels. |
| `rates` | `readonly number[] \| string` | `[]` | Rates to offer, in order, in place of the player's `defaultPlaybackRates`. HTML takes a space-separated list, such as `rates="1 1.5 2"`. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media exposes a meaningful selection. `unsupported` when the media has no such capability at all. |
| `rate` | `number` | |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-rate` | `number` | Current playback rate. |
| `data-disabled` | — | Present when playback rate selection is disabled. |
| `data-hidden` | — | Present when playback rate selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates playback rate availability (`available`, `unavailable`, `unsupported`). |
#### Events
| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |
---
# media-quality-radio-group
A menu radio group for selecting video quality
Creates radio items from the player video rendition state and selects automatic or manual quality.
## Import
```ts
import '@videojs/html/ui/quality-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```
## Anatomy
```html
```
## Behavior
The group is available when the configured media exposes more than one video rendition. The first generated option is `Auto`; selecting it returns control to adaptive bitrate selection. Pass `formatRendition` to customize visible rendition labels.
`` generates `` children. Add an optional `` with a single `` to customize each generated item.
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-quality` | `string` | Current quality value. |
| `data-disabled` | Present / absent | Present when quality selection is disabled. |
| `data-hidden` | Present / absent | Present when multiple renditions are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether multiple renditions are available. |
Unavailable groups receive the native `hidden` attribute.
## Accessibility
The group uses the menu radio group pattern.
The element receives an accessible label from the `label` property or defaults to `Quality`.
## Examples
### Basic usage
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-media {
width: 100%;
}
.menu-bar {
position: absolute;
right: 10px;
bottom: 10px;
}
.menu-bar:has([data-availability="unavailable"]) {
display: none;
}
.settings-trigger {
padding: 6px 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.35);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.menu {
--media-menu-side-offset: 8px;
box-sizing: border-box;
min-width: 180px;
max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
padding: 6px;
overflow: auto;
overscroll-behavior: none;
font-size: 14px;
color: white;
background: rgba(0, 0, 0, 0.88);
border-radius: 8px;
backdrop-filter: blur(10px);
}
.menu-group {
display: grid;
gap: 2px;
}
.menu-item {
display: flex;
gap: 8px;
align-items: center;
justify-content: space-between;
min-height: 32px;
padding: 0 10px;
font: inherit;
color: inherit;
cursor: pointer;
background: none;
border: 0;
border-radius: 6px;
}
.menu-item[data-highlighted] {
background: rgba(255, 255, 255, 0.16);
}
.menu-tier {
margin-left: 2px;
font-size: 10px;
}
.menu-badge {
margin-left: auto;
color: rgba(255, 255, 255, 0.72);
}
.menu-indicator {
opacity: 0;
}
media-menu-radio-item[aria-checked="true"] .menu-indicator {
opacity: 1;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/quality-radio-group';
```
## API Reference
### media-quality-radio-group
Menu radio group that generates an Auto `` plus one per video rendition, and shares the selected label and availability with an enclosing menu. An optional `` holding one `` customizes each generated item; its `data-part` `label`, `tier`, and `badge` descendants receive the rendition's text.
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether quality selection is disabled. |
| `formatRendition` (attribute `format-rendition`) | `((rendition: MediaVideoRendition) => Text \| string)` | `formatRenditionLabel` | Custom formatter for visible rendition labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: QualityRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media exposes a meaningful selection. `unsupported` when the media has no such capability at all. |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-quality` | `string` | Current quality value. |
| `data-disabled` | — | Present when quality selection is disabled. |
| `data-hidden` | — | Present when quality selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates quality availability (`available` or `unavailable`). |
#### Events
| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |
---
# media-time
Time display components for showing current time, duration, and remaining time in a video player
## Import
```ts
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```
## Anatomy
```html
```
## Behavior
Three display types — `current`, `duration`, and `remaining` — in digital format with smart padding:
- **Hours** are never padded (`1:05:30`, not `01:05:30`)
- **Minutes** are padded when hours are shown (`1:05:30`, but `5:30`)
- **Seconds** are always padded (`1:05`, not `1:5`)
Hour display is triggered when either the current value or the duration exceeds 1 hour, ensuring consistency within a Group. Remaining time displays a negative sign (customizable via the `negativeSign` prop).
Use `toggle` to let current displays switch between elapsed and remaining time, or remaining and duration displays switch between those two values. The initial display comes from `type`.
Before the media reports a duration or seekable range — while metadata is still loading, for example — no time value is available. A plain display still renders the formatted zero value but sets `data-unavailable`; a toggleable display is disabled instead: it sets `data-disabled`, leaves the tab order, and ignores activation until a value arrives.
```html
```
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-type` | `current` / `duration` / `remaining` | The type of time being displayed |
| `data-disabled` | Present / absent | Present when a toggleable display has no time value yet |
| `data-unavailable` | Present / absent | Present when a plain display has no time value yet |
The negative sign is rendered inside `` and can be hidden with CSS:
```css
[data-type="remaining"] > span[aria-hidden] {
display: none;
}
```
Dim a display while its value is unavailable:
```css
[data-disabled],
[data-unavailable] {
opacity: 0.5;
}
```
## Accessibility
Each `` has:
- `role="time"` and `datetime` for machine-readable time semantics
- `aria-label` for the static role label (“Current time”, “Duration”, “Remaining”)
No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator and negative sign are `aria-hidden="true"` because the accessible label already describes the value.
Toggleable time displays receive `role="button"`, `tabindex="0"`, and keyboard support for Enter and Space. Their `aria-label` starts with the action and includes the current value. Their `aria-description` explains which values the control toggles between.
While no time value is available, a toggleable display is disabled: it sets `aria-disabled="true"` and `tabindex="-1"`, drops the `aria-description`, changes its `aria-label` to “Media not loaded, unknown time.”, and ignores clicks and key presses. A plain display in the same state omits `datetime` and uses that same label.
## Examples
### Current Time
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
}
.video-player media-container video {
width: 100%;
}
.media-time {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
font-variant-numeric: tabular-nums;
color: black;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```
### Current / Duration
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
}
.video-player media-container video {
width: 100%;
}
.time-group {
position: absolute;
bottom: 10px;
left: 10px;
display: flex;
gap: 4px;
align-items: center;
padding-block: 8px;
padding-inline: 20px;
font-variant-numeric: tabular-nums;
color: black;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```
### Remaining
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
}
.video-player media-container video {
width: 100%;
}
.media-time {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
font-variant-numeric: tabular-nums;
color: black;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```
### Custom Separator
**index.html**
```html
of
```
**index.css**
```css
.video-player media-container {
position: relative;
}
.video-player media-container video {
width: 100%;
}
.time-group {
position: absolute;
bottom: 10px;
left: 10px;
display: flex;
gap: 4px;
align-items: center;
padding-block: 8px;
padding-inline: 20px;
font-variant-numeric: tabular-nums;
color: black;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```
### Custom Negative Sign
**index.html**
```html
```
**index.css**
```css
.video-player media-container {
position: relative;
}
.video-player media-container video {
width: 100%;
}
.media-time {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
font-variant-numeric: tabular-nums;
color: black;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```
## API Reference
### media-time
Displays a formatted time value (current, duration, or remaining).
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `{ key: string; text: string } \| string \| ((state: TimeState) => Text \| string)` | `''` | Custom label for accessibility. |
| `negativeSign` (attribute `negative-sign`) | `string` | `'-'` | Symbol prepended to remaining time. |
| `toggle` | `boolean` | `false` | Whether the time display can be toggled. |
| `type` | `'current' \| 'duration' \| 'remaining'` | `'current'` | Which time value to display. |
#### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `type` | `'current' \| 'duration' \| 'remaining'` | Time display type. |
| `disabled` | `boolean` | Whether the time toggle is disabled. |
| `unavailable` | `boolean` | Whether the non-interactive time value is unavailable. |
| `seconds` | `number` | Raw value in seconds. |
| `negative` | `boolean` | Whether the time value is negative (remaining time before end). |
| `text` | `string` | Formatted display text without sign (e.g., "1:30"). |
| `phrase` | `string` | Human-readable phrase (e.g., "1 minute, 30 seconds"). |
| `datetime` | `string` | ISO 8601 duration (e.g., "PT1M30S"). |
#### Data attributes
| Attribute | Type | Description |
| --- | --- | --- |
| `data-type` | `'current' \| 'duration' \| 'remaining'` | The type of time being displayed. |
| `data-disabled` | — | Present when the time toggle is disabled. |
| `data-unavailable` | — | Present when the non-interactive time value is unavailable. |
### media-time-group
Container for composed `` and `` displays.
### media-time-separator
Divider between time values. Hidden from screen readers.
---
# media-title
Displays the resolved content title for the current media
## Import
```ts
import '@videojs/html/ui/title';
```
## Anatomy
```html
```
## Behavior
The element renders the resolved title directly as text and owns that text: it replaces any authored content whenever the title updates. Set the title on the player instead.
```html
```
A title can come from two places. The player uses the first one that has a value:
1. The title you set on the player.
2. The title the media reports about itself.
If neither has a value, there is nothing to show and the title hides itself.
The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](https://deploy-preview-9819--vjs10-site.netlify.app/docs/framework/html/reference/api/feature-metadata), which the video and audio presets include.
`title` already means the tooltip on an element, so the player takes the title as `content-title`, reflected by the `contentTitle` property:
```ts
const player = document.querySelector("video-player");
player.contentTitle = "Sintel";
```
Set it to `null` to hand the title back to the media.
The component exposes `data-visible` while controls are visible. Use that hook to animate the title with the controls.
## Styling
When no title resolves, the element sets the native `hidden` attribute and `data-hidden`, so it takes up no space and a background or gradient never sits over empty space.
To fade the title in and out with the controls, use the root’s `data-visible` attribute:
```css
media-title {
opacity: 0;
transition: opacity 150ms ease-out;
}
media-title[data-visible] {
opacity: 1;
}
```
## Accessibility
The title is ordinary text, so it reaches assistive technology as content with no ARIA of its own. The native `hidden` attribute it sets when there is no title also removes it from the accessibility tree, so nothing is announced when there is nothing to announce.
Fading the title out with `opacity` leaves it readable by a screen reader while it is not painted. That is deliberate — the name of what is playing stays relevant whether or not the controls happen to be on screen.
The component does not name the player. To give the player region an accessible name, set `aria-label` or `aria-labelledby` on the container yourself.
## Examples
### Basic Usage
**index.html**
```html
Play
Pause
```
**index.css**
```css
.html-title-basic {
position: relative;
display: block;
}
.html-title-basic video {
display: block;
width: 100%;
}
/* The element sets native `hidden` until a title resolves, so the gradient
never sits over empty space without this demo doing anything. */
.html-title-basic__title {
position: absolute;
inset-inline: 0;
top: 0;
padding: 16px 20px 48px;
font-size: 16px;
font-weight: 500;
color: white;
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
pointer-events: none;
background: linear-gradient(to bottom, rgba(0, 0, 0, 0.7), transparent);
}
.html-title-basic__button {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.html-title-basic__button .show-when-paused {
display: none;
}
.html-title-basic__button .show-when-playing {
display: none;
}
.html-title-basic__button[data-paused] .show-when-paused {
display: inline;
}
.html-title-basic__button:not([data-paused]) .show-when-playing {
display: inline;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/title';
```
## API Reference
### State
State is reflected as data attributes for CSS styling.
| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | The resolved content title. Empty when no source supplied one. |
| `hidden` | `boolean` | Whether the component is hidden because no title is available. |
| `visible` | `boolean` | Whether the player controls are visible. |
### Data attributes
| Attribute | Description |
| --- | --- |
| `data-hidden` | Present when the element is hidden because no title is available. |
| `data-visible` | Present while the player controls are visible. |
---
# media-poster
Poster image component that displays a thumbnail until video playback starts
## Import
```ts
import '@videojs/html/ui/poster';
```
## Anatomy
```html
```
## Behavior
The poster shows before playback starts. Once the user plays or seeks, it hides; pausing does not bring it back. Loading a new source shows it again.
The ` ` child is optional. Leave it out and `` draws one of its own in its shadow DOM.
You can set the poster URL on the player. This is useful when you want to change the poster from inside a skin, or keep all your media metadata in one place:
```html
```
## Supply your own image
The component fills in a source only when you leave one out. `srcset`, `sizes`, `loading`, ``, and framework image components all stay available.
`` draws a fallback image in its shadow DOM and fills in its `src`. Put an ` ` inside it and the element uses yours instead, filling in its `src` the same way:
```html
```
Give that image a `src`, a `srcset`, or `` candidates and it is yours; the component leaves it alone:
```html
```
Inside a skin, slot your image instead. The skin carries a plain one that yours replaces:
```html
```
A skin can only style an ` ` you slot directly. Wrap one in a `` or a framework component and its sizing is yours.
## Styling
| Attribute | Values | Description |
| --- | --- | --- |
| `data-visible` | Present / absent | Present before playback starts |
| `data-loading` | Present / absent | Present while the image is fetching |
| `data-loaded` | Present / absent | Present once the image has loaded |
| `data-error` | Present / absent | Present when the image failed |
The three load attributes track the image on screen, including one you supplied yourself.
```css
media-poster:not([data-visible]) {
opacity: 0;
}
```
The image the element draws is exposed as a part. An image you supply is an ordinary child, so style it as a descendant:
```css
media-poster::part(image),
media-poster img {
object-fit: cover;
}
```
From inside a skin’s shadow root, an image slotted from outside needs `::slotted(img)` as well.
## Accessibility
Unlike the native `` attribute, this component lets you describe the poster for screen readers.
The image is decorative by default (`alt=""`), since a URL says nothing about what the image shows. When the poster carries meaning, say so:
```html
```
Whether a poster is informative or decorative is your judgment, per the [WAI guidelines](https://www.w3.org/WAI/tutorials/images/decorative/).
## Examples
### Basic Usage
**index.html**
```html
Play
Pause
```
**index.css**
```css
.video-player media-container {
position: relative;
display: block;
}
.video-player media-container video {
width: 100%;
}
.media-poster {
position: absolute;
inset: 0;
pointer-events: none;
transition: opacity 0.25s;
}
.media-poster:not([data-visible]) {
opacity: 0;
}
.media-poster img {
width: 100%;
height: 100%;
object-fit: cover;
}
.media-play-button {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 16px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.media-play-button .paused,
.media-play-button .playing {
display: none;
}
.media-play-button[data-paused] .paused {
display: inline;
}
.media-play-button:not([data-paused]) .playing {
display: inline;
}
```
**index.ts**
```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/poster';
```
## API Reference
### media-poster
`` — sets `src` on a poster image it does not own.
The image is a child, as in ``, but sourcing runs the other way around: `` treats the `src` on its ` ` as the fallback, while here an image with no source of its own is the one this element fills in. Give the child a `src`, a `srcset`, or `` candidates and it is yours, left alone.
Left empty, the element draws an image of its own in its shadow root. Supply one as a child to describe it or wrap it: `