Demo

Demo

Run Locally

Clone the project

git clone https://github.com/hunghg255/reactjs-player-media.git

Go to the project directory

cd reactjs-player-media

Install dependencies

pnpm install

Start the Demo server

npm run build:lib:dev
npm run playground

API Reference

Root

The main container component for the media player.

| Prop Name | Type | Description | |--------------------------|----------------------------------------------------------------------|-------------| | onPlay | () => void | Callback when media starts playing | | onPause | () => void | Callback when media is paused | | onEnded | () => void | Callback when playback ends | | onTimeUpdate | (time: number) => void | Callback when playback time updates | | onVolumeChange | (volume: number) => void | Callback when volume changes | | onMuted | (muted: boolean) => void | Callback when muted state changes | | onMediaError | (error: MediaError | null) => void | Callback when a media error occurs | | onPipError | (error: unknown, state: "enter" | "exit") => void | Callback when PiP error occurs | | onFullscreenChange | (fullscreen: boolean) => void | Callback when fullscreen state changes | | dir | "ltr" | "rtl" | Text direction | | label | string | Accessibility label (default: "Media player") | | tooltipSideOffset | number | Tooltip offset (default: 10) | | tooltipDelayDuration | number | Tooltip delay (default: 600) | | autoHide | boolean | Enable auto-hiding controls (default: false) | | disabled | boolean | Disable controls (default: false) | | withoutTooltip | boolean | Disable tooltips (default: false) |

Data Attributes

| Attribute | Description | |--------------------------|--------------------------------------------------| | [data-controls-visible]| Present when the controls are visible. | | [data-disabled] | Present when the media player is disabled. | | [data-state] | fullscreen, windowed |

Video

The video element, integrated with the player state.

Audio

The audio element, integrated with the player state.

Controls

A container for the media player controls.

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the controls are disabled. | | [data-state] | fullscreen, windowed | | [data-visible] | Present when the controls are visible. |

ControlsOverlay

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

Data Attributes

| Attribute | Description | |------------------|---------------------------------------------| | [data-state] | fullscreen, windowed | | [data-visible] | Present when the controls are visible. |

Loading

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

| Prop Name | Type | Description | |-----------|--------|-------------| | delay | number | Delay before showing loading indicator (default: 500) |

Error

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

| Prop Name | Type | Description | |-------------|----------------------------|-------------| | error | MediaError | null | Media error object | | label | string | Error label | | description | string | Error description | | onRetry | () => void | Callback on retry | | onReload | () => void | Callback on reload |

Data Attributes

| Attribute | Description | |----------------|----------------------------------| | [data-state] | fullscreen, windowed |

VolumeIndicator

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

Play

A button to play or pause the media.

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. | | [data-state] | on, off |

SeekBackward

A button to seek backward in the media.

| Prop Name | Type | Description | |-----------|--------|-------------| | seconds | number | Seconds to seek backward (default: 5) |

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. |

SeekForward

A button to seek forward in the media.

| Prop Name | Type | Description | |-----------|--------|-------------| | seconds | number | Seconds to seek forward (default: 10) |

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. |

Seek

A slider component to seek through the media playback.

| Prop Name | Type | Description | |--------------------------|----------------------------------------------------------------------|-------------| | withTime | boolean | Show current/remaining time (default: false) | | withoutChapter | boolean | Hide chapter markers (default: true) | | withoutTooltip | boolean | Disable seek tooltip (default: false) | | tooltipThumbnailSrc | string | (time: number) => string | Thumbnail for seek preview | | tooltipTimeVariant | "current" | "progress" | Tooltip time display (default: "current") | | tooltipSideOffset | number | Tooltip offset (default: 10) | | tooltipCollisionBoundary | Element | Element[] | Tooltip collision boundary | | tooltipCollisionPadding | number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | Tooltip collision padding (default: 10) |

Data Attributes

| Attribute | Description | |--------------------------------------------|-------------------------------------------------------| | [data-disabled] | Present when the slider is disabled. | | [data-hovering] | Present when the seek slider is being actively hovered.| | [data-slider=''] | Present on the seek slider. | | [data-slot='media-player-seek-container']| The container for the seek slider. | | [data-slot='media-player-seek'] | The root for the seek slider. | | [data-slot='media-player-seek-buffered'] | The buffered progress indicator within the track. | | [data-slot='media-player-seek-hover-range']| The hover preview range indicator. | | [data-slot='media-player-seek-chapter-separator']| Chapter separators displayed on the track. | | [data-slot='media-player-seek-thumbnail'] | The thumbnail preview container in the tooltip. | | [data-slot='media-player-seek-chapter-title']| The chapter title in the tooltip. | | [data-slot='media-player-seek-time'] | The time display in the tooltip. |

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",
  )}
/>

Volume

A slider component to control the media volume.

| Prop Name | Type | Description | |-------------|---------|-------------| | expandable | boolean | Expand slider on hover (default: false) |

Data Attributes

| Attribute | Description | |--------------------------------------------|---------------------------------------------| | [data-disabled] | Present when the volume control is disabled.| | [data-slider=''] | Present on the volume slider. | | [data-slot='media-player-volume-container']| The container for the volume slider. | | [data-slot='media-player-volume-trigger'] | The trigger for the volume slider. | | [data-slot='media-player-volume'] | The root for the volume slider. | | [data-state] | on, off |

Time

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

| Prop Name | Type | Description | |-----------|-----------------------------------|-------------| | variant | "progress" | "remaining" | "duration" | Time display format (default: "progress") |

PlaybackSpeed

A select dropdown to control the media playback speed.

| Prop Name | Type | Description | |-------------|----------------|-------------| | defaultOpen | boolean | Dropdown open by default (default: false) | | open | boolean | Dropdown open (default: false) | | onOpenChange| (open: boolean) => void | Callback on open/close | | modal | boolean | Dropdown is modal (default: false) | | sideOffset | number | Dropdown offset (default: 10) | | speeds | number[] | Playback speed options (default: [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]) |

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the select is disabled. |

Loop

A button to toggle loop mode.

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. | | [data-state] | on, off |

Fullscreen

A button to toggle fullscreen mode.

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. | | [data-state] | on, off |

PiP (Picture in picture)

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

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. | | [data-state] | on, off |

Captions

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

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. | | [data-state] | on, off |

Download

A button to download the media file.

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. |

Settings

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]} />

Data Attributes

| Attribute | Description | |-------------------|---------------------------------------------| | [data-disabled] | Present when the button is disabled. |

Accessibility

Keyboard Interactions

| Keys | Description | |---------------------------------------|-----------------------------------------------------| | Space, K | Toggles play/pause. | | ArrowRight | Seeks forward 5 seconds (video only). | | ArrowLeft | Seeks backward 5 seconds (video only). | | J | Seeks backward 10 seconds (video only). | | L | Seeks forward 10 seconds (video only). | | Shift + ArrowRight | Seeks forward 5 seconds (audio only). | | Shift + ArrowLeft | Seeks backward 5 seconds (audio only). | | 0–9 | Seeks to 0%-90% of duration. | | Home | Seeks to beginning. | | End | Seeks to end. | | ArrowUp | Increases volume (video only). | | ArrowDown | Decreases volume (video only). | | M | Toggles mute. | | R | Toggles repeat mode. | | F | Toggles fullscreen. | | Escape | Exits fullscreen when in fullscreen mode. | | > | Increases playback speed. | | < | Decreases playback speed. | | C | Toggles captions (video only, if available). | | P | Toggles Picture-in-Picture. | | D | Downloads the media file (if download button is present). |

License

MIT