https://github.com/hunghg255/reactjs-player-media
React Media Player
https://github.com/hunghg255/reactjs-player-media
audio media player react-media react-media-player react-player shadcn video
Last synced: 11 months ago
JSON representation
React Media Player
- Host: GitHub
- URL: https://github.com/hunghg255/reactjs-player-media
- Owner: hunghg255
- License: mit
- Created: 2025-07-02T10:04:25.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-03T05:46:52.000Z (about 1 year ago)
- Last Synced: 2025-07-25T07:58:40.248Z (12 months ago)
- Topics: audio, media, player, react-media, react-media-player, react-player, shadcn, video
- Language: TypeScript
- Homepage: https://reactjs-player-media-playground.vercel.app/
- Size: 690 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
A modern media player based on tiptap and shadcn ui for React
## Demo
[Demo](https://reactjs-player-media-playground.vercel.app/)
## Run Locally
Clone the project
```bash
git clone https://github.com/hunghg255/reactjs-player-media.git
```
Go to the project directory
```bash
cd reactjs-player-media
```
Install dependencies
```bash
pnpm install
```
Start the Demo server
```bash
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> | 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
```tsx
```
### 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
```tsx
```
#### 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](./LICENSE)