Media Player

Installation

Prerequisites: Before installing the media player component, you'll need to update your existing shadcn/ui components to support portal containers.

function DropdownMenuContent({
  className,
+ container,
  sideOffset = 4,
  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content> & {
+  container?: DropdownMenuPrimitive.DropdownMenuPortalProps["container"];
+}) {
  return (
-    <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Portal container={container}>

function TooltipContent({
  className,
  sideOffset = 0,
+ container,
  children,
  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Content> & {
+  container?: TooltipPrimitive.TooltipPortalProps["container"];
+}) {
  return (
-    <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Portal container={container}>

pnpm dlx shadcn@latest add @diceui/media-player

Layout

Import the parts, and compose them together.

import {
  MediaPlayer,
  MediaPlayerVideo,
  MediaPlayerAudio,
  MediaPlayerLoading,
  MediaPlayerError,
  MediaPlayerVolumeIndicator,
  MediaPlayerControls,
  MediaPlayerControlsOverlay,
  MediaPlayerPlay,
  MediaPlayerSeekBackward,
  MediaPlayerSeekForward,
  MediaPlayerVolume,
  MediaPlayerSeek,
  MediaPlayerTime,
  MediaPlayerPlaybackSpeed,
  MediaPlayerLoop,
  MediaPlayerCaptions,
  MediaPlayerFullscreen,
  MediaPlayerDownload,
  MediaPlayerSettings,
} from "@/components/ui/media-player";
 
return (
  <MediaPlayer>
    <MediaPlayerVideo>
      <source src="..." type="video/mp4" />
    </MediaPlayerVideo>
    <MediaPlayerLoading />
    <MediaPlayerError />
    <MediaPlayerVolumeIndicator />
    <MediaPlayerControls>
      <MediaPlayerControlsOverlay />
      <MediaPlayerPlay />
      <MediaPlayerSeekBackward />
      <MediaPlayerSeekForward />
      <MediaPlayerVolume />
      <MediaPlayerSeek />
      <MediaPlayerTime />
      <MediaPlayerPlaybackSpeed />
      <MediaPlayerLoop />
      <MediaPlayerCaptions />
      <MediaPlayer.PiP />
      <MediaPlayer.Fullscreen />
      <MediaPlayer.Download />
    </MediaPlayer.Controls>
  </MediaPlayer.Root>
)

Examples

Audio Player

Use the Audio component instead of Video for audio playback.

With Settings Menu

Media player with a settings menu with playback speed, caption option, and resolution selector.

HLS Playback

Media player with HLS (HTTP Live Streaming) support for adaptive bitrate streaming.

This example demonstrates using the Mux Video React package as the video element to enable HLS playback.

With Error Handling

Media player with custom error handling and retry functionality.

With Playlist

A media player example that includes a playlist, similar to music streaming applications.

API Reference

MediaPlayer

The main container component for the media player.

MediaPlayerVideo

The video element, integrated with the player state.

MediaPlayerAudio

The audio element, integrated with the player state.

MediaPlayerControls

A container for the media player controls.

ControlsOverlay

Displays as a subtle backdrop that improves readability for media controls.

MediaPlayerLoading

A loading indicator that appears when media is loading, similar to YouTube/Netflix style.

MediaPlayerError

An error component that displays when media playback encounters an error, with retry and reload options.

VolumeIndicator

A volume indicator that appears when the volume is changed with keyboard interactions.

MediaPlayerPlay

A button to play or pause the media.

SeekBackward

A button to seek backward in the media.

SeekForward

A button to seek forward in the media.

MediaPlayerSeek

A slider component to seek through the media playback.

Styling

<MediaPlayer.Seek 
  className={
    cn(
      "[&_[data-slot='media-player-seek-buffered']]:bg-primary/60",
      "[&_[data-slot='media-player-seek-hover-range']]:bg-primary/70",
      "[&_[data-slot='media-player-seek-chapter-separator']]:w-1 [&_[data-slot='media-player-seek-chapter-separator']]:bg-muted",
      "[&_[data-slot='media-player-seek-thumbnail']]:border-2 [&_[data-slot='media-player-seek-thumbnail']]:border-ring"
    )
  }
/>

MediaPlayerVolume

A slider component to control the media volume.

MediaPlayerTime

Displays the current time, duration, or remaining time of the media.

PlaybackSpeed

A select dropdown to control the media playback speed.

MediaPlayerLoop

A button to toggle loop mode.

MediaPlayerFullscreen

A button to toggle fullscreen mode.

PiP (Picture in picture)

A button to toggle picture in picture mode (video only).

MediaPlayerCaptions

A button to toggle captions or subtitles (video only).

MediaPlayerDownload

A button to download the media file.

MediaPlayerSettings

A dropdown menu with playback speed selector, caption selector, and resolution selector.

Features:

• Playback speed control with customizable speeds
• Video quality/resolution selection (when available)
• Captions/subtitles control
• Organized in a clean dropdown interface

<MediaPlayer.Settings 
  speeds={[0.5, 0.75, 1, 1.25, 1.5, 2]}
/>

Accessibility

Keyboard Interactions

Credits

• FASSounds - For the audio file used in basic examples.
• Pika - For the video file used in basic examples.
• Elephants Dream - Open movie by the Blender Foundation, used in settings demo under Creative Commons Attribution 2.5.
• Mux - For HLS video streaming and VTT files used in HLS and settings demos.
• Media Chrome - For VTT chapter and caption files used in examples.
• RandomMind - For "Medieval: Battle" track used in playlist demo, available under CC0 from OpenGameArt.org.
• The Lemming Shepherds - For "City Lights" track used in playlist demo.
• Picsum - For placeholder cover images used in playlist demo.