Controls
The control bar
Section titled “The control bar”| Attribute | Effect |
|---|---|
| (nothing) | Controls always visible (default). |
controls-visible="false" | Control bar disabled. Clicking the video still plays/pauses. |
controls-hide-on-hover="true" | Controls visible, but hidden while the mouse is over the player. |
hide-on-play-delay="3" | Fades the controls out during playback after 3 s without activity. |
Auto-hide during playback
Section titled “Auto-hide during playback”With hide-on-play-delay, the controls fade out once playback reaches that second and after that many
seconds without activity. Mouse movement, a click, a tap or a key press bring them back. They stay visible
while the pointer is over the bar or a menu is open, and while the video is paused. Each hide fires
vega-player:hidden.
<vega-player src="/video.mp4" hide-on-play-delay="2"></vega-player>Individual buttons
Section titled “Individual buttons”| Attribute | Effect |
|---|---|
show-stop-button | Shows the stop button (hidden by default). |
hide-play-button | Hides the large centre play button. |
hide-fullscreen-button | Hides the fullscreen button. |
show-playback-rate | Shows the speed menu (0.25× to 2×). |
enable-pip | Shows the Picture-in-Picture button where supported. |
enable-chromecast | Shows the Cast button once the Cast SDK has loaded. |
The captions and quality buttons appear automatically when you set captions-src or qualities.
Play button
Section titled “Play button”<vega-player play-btn-size="lg" play-btn-color="rgba(255,255,255,0.95)"></vega-player>play-btn-size:sm,md(default) orlg.play-btn-color: any CSS color.play-btn-icon: an image URL, or inline SVG / icon-font markup (sanitised: scripts, event handlers and external links are removed).
<vega-player play-btn-icon='<svg viewBox="0 0 24 24" fill="currentColor"><circle cx="12" cy="12" r="6"/></svg>'></vega-player>Progress bar
Section titled “Progress bar”Click, or drag the thumb with a mouse, pen or finger. While dragging, the preview shows the target time (and a thumbnail) and the video only seeks when you release. The lighter bar shows how much of the video around the current position is downloaded. See Seek preview & thumbnails.
Volume
Section titled “Volume”- Desktop: hovering or focusing the speaker icon opens a vertical slider; clicking the icon mutes.
- Touch screens: the first tap opens the slider, the next ones mute and unmute.
- iPhone and iPad: only the hardware buttons can change the volume, so the slider is hidden and only mute is available.
- Keyboard: the slider is a focusable ARIA slider: arrows change the volume, Home mutes, End sets 100%.
Auto-hiding the volume slider
Section titled “Auto-hiding the volume slider”Once the slider opens (hover, click, keyboard focus, ↑/↓ or a volume change) it stays
visible for volume-hide-delay seconds, even if the mouse leaves, and then hides, even if the mouse is
still over it. Each new interaction restarts the countdown.
<vega-player src="/video.mp4" volume-hide-delay="4"></vega-player>Responsive controls
Section titled “Responsive controls”The player uses container queries, so its controls adapt to its own width, not the window’s.
| Player width | Behaviour |
|---|---|
| < 200px | Compact: stop, fullscreen, time, volume slider and modal description are hidden; no seek preview. |
| 200–350px | Smaller controls; stop, time and volume slider hidden; seek preview shows the time only. |
| 350–500px | Reduced sizes, shorter volume slider, smaller thumbnails. |
| 500–700px | Slightly reduced sizes. |
| > 700px | Full size. |
Pause when scrolled away
Section titled “Pause when scrolled away”<vega-player src="/video.mp4" pause-offscreen></vega-player>The video pauses when the player leaves the screen. With pause-offscreen="resume" it starts again when you
scroll back, handy for a hero video. It never pauses while in fullscreen or Picture-in-Picture.