MediaPlayer
Composable audio and video player primitives built on Media Chrome.
Quick Preview
Usage
import {
MediaPlayer,
MediaPlayerControls,
MediaPlayerControlsOverlay,
MediaPlayerError,
MediaPlayerFullscreen,
MediaPlayerPiP,
MediaPlayerPlay,
MediaPlayerPlaybackSpeed,
MediaPlayerSeek,
MediaPlayerSeekBackward,
MediaPlayerSeekForward,
MediaPlayerTime,
MediaPlayerVideo,
MediaPlayerVolume,
} from "@giddaa-housing/ui/media-player";
<MediaPlayer>
<MediaPlayerVideo>
<source src="/assets/cloud.mp4" type="video/mp4" />
</MediaPlayerVideo>
<MediaPlayerError />
<MediaPlayerControls className="flex-col items-start gap-2.5">
<MediaPlayerControlsOverlay />
<MediaPlayerSeek />
<div className="flex w-full items-center gap-2">
<div className="flex flex-1 items-center gap-2">
<MediaPlayerPlay />
<MediaPlayerSeekBackward />
<MediaPlayerSeekForward />
<MediaPlayerVolume expandable />
<MediaPlayerTime />
</div>
<div className="flex items-center gap-2">
<MediaPlayerPlaybackSpeed />
<MediaPlayerPiP />
<MediaPlayerFullscreen />
</div>
</div>
</MediaPlayerControls>
</MediaPlayer>;Examples
Captions, Chapters, and Settings
Add <track> elements to the video for captions and chapters. MediaPlayerCaptions
toggles captions on and off, and MediaPlayerSettings opens a menu with playback
speed and caption language submenus. Chapter cues split the timeline into segments
and label the seek preview.
Error State
MediaPlayerError overlays the player when the media fails to load, with retry and
reload actions.
Audio
Use MediaPlayerAudio with the same control primitives for audio-only layouts.
Minimal Audio
Compose a smaller player by changing the root and controls classes.
Behavior
- Controls fade out after 2.5 seconds of inactivity while video plays, and reappear on pointer movement, keyboard focus, or pause. Audio players keep controls visible.
- Dragging the timeline scrubs smoothly: the thumb follows the pointer, seeks are throttled to animation frames, and the position holds until the media catches up.
- Hovering the timeline shows the target time, plus a thumbnail when the media provides a preview (storyboard) track and a chapter title when chapters exist.
- The timeline shows buffered ranges as a lighter strip behind the progress bar.
Keyboard Shortcuts
Shortcuts work while focus is inside the player.
| Key | Action |
|---|---|
Space / K | Toggle play/pause |
M | Toggle mute |
F | Toggle fullscreen |
C | Toggle captions |
← / → | Seek back / forward 5 seconds |
Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
MediaPlayer | Media Chrome controller props | - | Root controller that coordinates media state, auto-hiding controls, and keyboard shortcuts. |
MediaPlayerVideo | native video props | playsInline=true | Video element with slot="media" applied. Pass <source> and <track> children as needed. |
MediaPlayerAudio | native audio props | - | Audio element with slot="media" applied. |
MediaPlayerControls | native div props | - | Positioned control bar that fades with player activity. Override layout with className. |
MediaPlayerControlsOverlay | native div props | - | Decorative gradient layer for controls over video. |
MediaPlayerSeek | native div props, onValueChange, step, withTime | step=5, withTime=true | Timeline control with smooth scrubbing. withTime shows the hover preview (time, thumbnail, chapter). |
MediaPlayerVolume | mute button props, expandable, rangeClassName | expandable=false | Mute button plus volume range. |
MediaPlayerPlaybackSpeed | button props, rates | rates=[0.5…2] | Menu of playback speeds anchored to the current rate. |
MediaPlayerCaptions | button props | - | Toggles captions. Disabled until the media exposes subtitle tracks. |
MediaPlayerSettings | button props, rates | rates=[0.5…2] | Settings menu with speed and caption submenus. |
MediaPlayerError | native div props | - | Error overlay with retry/reload actions. Renders only when the media errors; pass children to replace the default content. |
| control buttons | Media Chrome button props | - | Play, seek backward/forward, time, PiP, fullscreen, and loop controls. |
Accessibility
- Provide captions or subtitles with
<track kind="captions">when video includes speech. - The player root is a focusable region; all shortcuts are also reachable through the labeled controls.
- Use visible or implicit labels from Media Chrome controls; add
aria-labeloverrides when surrounding context needs more specificity. - Keep media URLs, permissions, analytics, and product-specific state in the consuming app.