Looking for the old docs? Go here

Core

Player

This is the top-most component in the library used to group media elements and control the flow of media state.

See the following sections for more information:

  • The loading guide covers how to handle loading various media resources.
  • The events guide covers the basics on how to listen and track updates.
  • The state management guide covers how to read, update, and subscribe to state changes.
  • The API pages cover how to interact with various player APIs and hooks.
HTMLAttributes
Ref<MediaPlayerInstance>

All media components exist inside the <MediaPlayer> component. This component's main responsibilities are to manage media state updates, dispatch media events, handle media requests, and expose media state through HTML attributes and CSS properties for styling purposes.

import { MediaPlayer, type MediaPlayerProps } from "@vidstack/react";
<MediaPlayer src="...">
  <MediaProvider />
</MediaPlayer>
PropTypeDefault
src
any
undefined
aspectRatio
string
undefined
asChild
boolean
false
children
ReactNode
null
artist
string
''
artwork
MediaImage[]
null
autoPlay
boolean
false
autoplay
boolean
false
clipEndTime
number
0
clipStartTime
number
0
controls
boolean
false
controlsDelay
number
2000
crossOrigin
mixed
null
crossorigin
mixed
null
currentTime
number
0
duration
number
-1
fullscreenOrientation
string
'landscape'
googleCast
GoogleCastOptions
{}
hideControlsOnMouseLeave
boolean
false
keyDisabled
boolean
'false'
keyShortcuts
MediaKeyShortcuts
MEDIA_KEY_SHORTCUTS
keyTarget
MediaKeyTarget
`player`
liveEdgeTolerance
number
10
load
MediaLoadingStrategy
'visible'
logLevel
LogLevel
__DEV__ ? 'warn' : 'silent'
loop
boolean
false
minLiveDVRWindow
number
30
muted
boolean
false
paused
boolean
true
playbackRate
number
1
playsInline
boolean
false
playsinline
boolean
false
poster
string
''
posterLoad
MediaPosterLoadingStrategy
'visible'
preferNativeHLS
boolean
false
preload
string
'metadata'
storage
string
null
streamType
MediaStreamType
'unknown'
title
string
''
viewType
MediaViewType
'unknown'
volume
number
1
import { MediaPlayer, MediaPlayerInstance } from "@vidstack/react"

const ref = useRef<MediaPlayerInstance>(null),
  { /* state props */ } = useStore(MediaPlayerInstance, ref);

<MediaPlayer ref={ref}>
PropTypeDefault
artist
string
''
artwork
object
null
audioGain
number
null
audioTrack
object
null
audioTracks
object
[]
autoPlay
boolean
false
autoPlayError
object
null
autoQuality
boolean
false
buffered
object
new TimeRange()
bufferedEnd
number
undefined
bufferedStart
number
undefined
canAirPlay
boolean
false
canFullscreen
boolean
false
canGoogleCast
boolean
false
canLoad
boolean
false
canLoadPoster
boolean
false
canOrientScreen
boolean
canOrientScreen()
canPictureInPicture
boolean
false
canPlay
boolean
false
canSeek
boolean
undefined
canSetAudioGain
boolean
false
canSetPlaybackRate
boolean
true
canSetQuality
boolean
true
canSetVolume
boolean
false
clipEndTime
number
0
clipStartTime
number
0
controls
boolean
false
controlsHidden
boolean
undefined
controlsVisible
boolean
false
crossOrigin
string
null
currentSrc
object
undefined
currentTime
number
undefined
duration
number
undefined
ended
boolean
false
error
object
null
fullscreen
boolean
false
hasCaptions
boolean
undefined
height
number
0
iOSControls
boolean
undefined
isAirPlayConnected
boolean
undefined
isGoogleCastConnected
boolean
undefined
lastKeyboardAction
object
null
live
boolean
undefined
liveEdge
boolean
undefined
liveEdgeStart
number
undefined
liveEdgeTolerance
number
10
liveEdgeWindow
number
undefined
logLevel
string
__DEV__ ? 'warn' : 'silent'
loop
boolean
undefined
mediaHeight
number
0
mediaType
string
'unknown'
mediaWidth
number
0
minLiveDVRWindow
number
60
muted
boolean
false
nativeControls
boolean
undefined
orientation
string
'landscape'
paused
boolean
true
pictureInPicture
boolean
false
playbackRate
number
1
played
object
new TimeRange()
playing
boolean
false
playsInline
boolean
false
pointer
string
'fine'
poster
string
undefined
preload
string
'metadata'
qualities
object
[]
quality
object
null
remotePlaybackInfo
object
null
remotePlaybackLoader
object
null
remotePlaybackState
string
'disconnected'
remotePlaybackType
string
'none'
seekable
object
new TimeRange()
seekableEnd
number
undefined
seekableStart
number
undefined
seekableWindow
number
undefined
seeking
boolean
false
source
object
{ src: '', type: '' }
sources
object
[]
started
boolean
false
streamType
string
undefined
textTrack
object
null
textTracks
object
[]
title
string
undefined
userBehindLiveEdge
boolean
false
viewType
string
undefined
volume
number
1
waiting
boolean
false
width
number
0
CallbackType
onAbort
function
onAudioGainChange
function
onAudioTrackChange
function
onAudioTracksChange
function
onAutoPlay
function
onAutoPlayChange
function
onAutoPlayFail
function
onCanLoad
function
onCanLoadPoster
function
onCanPlay
function
onCanPlayThrough
function
onControlsChange
function
onDestroy
function
onDurationChange
function
onEmptied
function
onEnd
function
onEnded
function
onError
function
onFullscreenChange
function
onFullscreenError
function
onLiveChange
function
onLiveEdgeChange
function
onLoadStart
function
onLoadedData
function
onLoadedMetadata
function
onLoopChange
function
onMediaAirplayRequest
function
onMediaAudioGainChangeRequest
function
onMediaAudioTrackChangeRequest
function
onMediaEnterFullscreenRequest
function
onMediaEnterPipRequest
function
onMediaExitFullscreenRequest
function
onMediaExitPipRequest
function
onMediaGoogleCastRequest
function
onMediaLiveEdgeRequest
function
onMediaMuteRequest
function
onMediaOrientationLockRequest
function
onMediaOrientationUnlockRequest
function
onMediaPauseControlsRequest
function
onMediaPauseRequest
function
onMediaPlayRequest
function
onMediaPlayerConnect
function
onMediaPosterStartLoading
function
onMediaQualityChangeRequest
function
onMediaRateChangeRequest
function
onMediaResumeControlsRequest
function
onMediaSeekRequest
function
onMediaSeekingRequest
function
onMediaStartLoading
function
onMediaTextTrackChangeRequest
function
onMediaTypeChange
function
onMediaUnmuteRequest
function
onMediaUserLoopChangeRequest
function
onMediaVolumeChangeRequest
function
onOrientationChange
function
onPause
function
onPictureInPictureChange
function
onPictureInPictureError
function
onPlay
function
onPlayFail
function
onPlaying
function
onPlaysInlineChange
function
onPosterChange
function
onProgress
function
onProviderChange
function
onProviderLoaderChange
function
onProviderSetup
function
onQualitiesChange
function
onQualityChange
function
onRateChange
function
onRemotePlaybackChange
function
onReplay
function
onSeeked
function
onSeeking
function
onSourceChange
function
onSourcesChange
function
onStalled
function
onStarted
function
onStreamTypeChange
function
onSuspend
function
onTextTrackChange
function
onTextTracksChange
function
onTimeUpdate
function
onTitleChange
function
onVdsLog
function
onVideoPresentationChange
function
onViewTypeChange
function
onVolumeChange
function
onWaiting
function
import { MediaPlayer, type MediaPlayerInstance } from "@vidstack/react"

const ref = useRef<MediaPlayerInstance>(null);

useEffect(() => { /* Use props/methods here. */ }, [])

<MediaPlayer ref={ref}>
PropType
audioTracks
AudioTrackList
canPlayQueue
RequestQueue
orientation
ScreenOrientationController
provider
AnyMediaProvider
qualities
VideoQualityList
remoteControl
MediaRemoteControl
state
MediaPlayerState
textRenderers
TextRenderers
textTracks
TextTrackList
enterFullscreen
method
enterPictureInPicture
method
exitFullscreen
method
exitPictureInPicture
method
pause
method
play
method
requestAirPlay
method
requestGoogleCast
method
seekToLiveEdge
method
setAudioGain
method
startLoading
method
startLoadingPoster
method
subscribe
method
/* Example. */
.component[data-foo] {}
NameDescription
data-airplay
Whether AirPlay is connected.
data-autoplay
Autoplay has successfully started.
data-autoplay-error
Autoplay has failed to start.
data-buffering
Media is not ready for playback or waiting for more data.
data-can-airplay
Whether AirPlay is available.
data-can-fullscreen
Fullscreen mode is available.
data-can-google-cast
Whether Google Cast is available.
data-can-load
Media can now begin loading.
data-can-pip
Picture-in-Picture mode is available.
data-can-play
Media is ready for playback.
data-can-seek
Seeking operations are permitted.
data-captions
Captions are available and visible.
data-controls
Controls are visible.
data-ended
Playback has ended.
data-error
Issue with media loading/playback.
data-fullscreen
Fullscreen mode is active.
data-google-cast
Whether Google Cast is connected.
data-ios-controls
iOS controls are visible.
data-load
Specified load strategy.
data-live
Media is live stream.
data-live-edge
Playback is at the live edge.
data-loop
Media is set to replay on end.
data-media-type
Current media type (audio/video).
data-muted
Whether volume is muted (0).
data-orientation
Current screen orientation (landscape/portrait).
data-paused
Whether playback is paused.
data-pip
Picture-in-picture mode is active.
data-playing
Playback is active.
data-playsinline
Media should play inline by default (iOS).
data-pointer
The user's pointer device type (coarse/fine).
data-preview
The user is interacting with the time slider.
data-remote-type
The remote playback type (airplay/google-cast).
data-remote-state
The remote playback state (connecting/connected/disconnected).
data-seeking
User is seeking to a new playback position.
data-started
Media playback has started.
data-stream-type
Current stream type.
data-view-type
Current view type (audio/video).
data-waiting
Media is waiting for more data to resume playback.
data-focus
Whether player is being keyboard focused.
data-hocus
Whether player is being keyboard focused or hovered over.