CldVideoPlayer Configuration

General Props

Prop Name	Type	Default	Description	Example
className	string	-	Additional class names added to the video container	`"my-video-player"`
height	string/number	-	Required: Player height	`1080`
id	string	-	Video instance ID, defaults to src value	`"my-video"`
logo	boolean/object	See Below	Logo to display in Player UI	See Logo Below
onDataLoad	Function	-	Triggered when video metadata is loaded	See Events Below
onError	Function	-	Triggered on video error	See Events Below
onMetadataLoad	Function	-	Triggered when video data is loaded	See Events Below
onPause	Function	-	Triggered on video pause	See Events Below
onPlay	Function	-	Triggered on video play	See Events Below
onEnded	Function	-	Triggered when video has ended play	See Events Below
playerRef	Ref	-	React ref to access Player instance	See Refs Below
poster	string/object	-	Customize the video's poster	See Poster Below
src	string	-	Required: Video public ID	`"videos/my-video"`
videoRef	Ref	-	React ref to access video element	See Refs Below
width	string/number	-	Required: Player width	`1920`

Player visuals Props

Prop Name	Type	Default	Description	Example
aiHighlightsGraph	boolean	`false`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
bigPlayButton	boolean/string	`true`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
colors	object	See below	Player chrome colors	See Colors Below
controlBar	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
controls	boolean	`true`	Show player controls	`true`
floatingWhenNotVisible	string	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
fluid	boolean	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
fontFace	string	-	Player UI font. Uses Google Fonts.	`"Source Serif Pro"`
hideContextMenu	boolean	`false`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
interactionAreas	any	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
playbackRates	array	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
playlistWidget	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
posterOptions	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
showJumpControls	boolean	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
showLogo	boolea	`true`	Show the Cloudinary logo on Player	`false`
seekThumbnails	boolean	`true`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
videoJS	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs

Player Behavior Props

Prop Name	Type	Default	Description	Example
autoplay	string/boolean	`"never"`	When, if, should the video automatically play. Note that if the value passed is a boolean then the value will be passed to `autoplay` but if the value passed is a string then the value will be passed to `autoplayMode` See `autoplayMode` in Video Player docs (opens in a new tab)	`"on-scroll"`/`true`
autoShowRecommendations	boolean	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
loop	boolean	`false`	Loop the video	`true`
maxTries	number	`3`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
muted	boolean	`false`	Load muted by default	`true`
playedEventPercents	array	`[25, 50, 75, 100]`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
playedEventTimes	array/null	`null`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
playsinline	boolean	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
videoTimeout	number	`55000`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
withCredentials	boolean	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs

Video Config Props

Prop Name	Type	Default	Description	Example
chapters	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
preload	string	`auto`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
publicId	string	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
sourceTransformation	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
sourceTypes	array	-	Streaming format	`['hls']`
transformation	object/array	-	Transformations to apply to the video	`{ width: 200, height: 200, crop: 'fill' }`

Ads And Analytics Props

Prop Name	Type	Default	Description	Example
ads	object	-	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
analytics	boolean	`false`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs
allowUsageReport	boolean	`true`	Check Cloudinary Video Player Api Docs	Check Cloudinary Video Api Docs

Missing an option from the Video Player docs (opens in a new tab) you'd like to see? Create an issue (opens in a new tab)!

Config & Delivery

Prop Name	Type	Default	Description	Example
cname	string	-	The custom domain name (CNAME) to use for building URLs, requires secure: false.	mycname.com
privateCdn	boolean	false	Set this parameter to true if you are an Advanced plan user with a private CDN distribution	`true`
secureDistribution	string	-	The custom domain name (CNAME) to use for building URLs, requires secure: true.	mycname.com
queryParams	string/object	-	Query parameters to append to video URL	`{myParam: 'value'}`

Missing an option from the Video Player docs (opens in a new tab) you'd like to see? Create an issue (opens in a new tab)!

Customization

Logo

The logo prop gives the option to customize the player's logo.

logo defaults to true, showing the Cloudinary logo and linking to https://cloudinary.com (opens in a new tab) when clicked.

When logo is set to false, no logo will be displayed.

To customize the logo, the following options are available in the form of an object:

Prop Name	Type	Default	Description
imageUrl	string	-	Image URL for player logo.
onClickUrl	string	-	URL to browse to on logo click.

Poster

The poster prop optionally takes a string or object to customize the generated poster.

When passing a string, you can either pass a Cloudinary Public ID or a remote URL to rendered the desired image.

When passing an object, use same configuration and API as getCldImageUrl to customize the image. You can either specify a src option with a custom public ID or omit the src, which will use the video's ID to render an automatically generated preview image.

View examples.

Theme Colors

The colors prop takes an object that can control what colors are used in the player:

Prop Name	Type	Default	Description
accent	string	`"#FF620C"`	Seek bar, volume control and for highlighting interactions.
base	string	`"#000000"`	Player controls bar, information bar, central play button, and right-click context menu.
text	string	`"#FFFFFF"`	All the text and icons that are present within the video player UI.

Learn more about the color scheme options and how they're used on the Cloudinary docs (opens in a new tab).

Localization

You can add custom localization options to control the languages of the player provides labels in.

Prop Name	Type	Default	Description
language	string	-	The language of the player's labels.
languages	object	-	Language configuration and label overrides.

Uses Vide.js JSON format for localization customization: https://videojs.com/guides/languages/#json-format (opens in a new tab)

Player APIs

Event Handlers

The event props allow you to pass in a function that is called whenever the associated event occurs.

For instance, in order to trigger an event whenever a video is paused:

<CldVideoPlayer onPause={({ player }) => {
  const duration = player.duration();
}} ... />

Refs

The playerRef and videoRef props give you the ability to pass in your own ref to gain access to both the Player instance as well as the HTML video element on which the player is mounted.

To do this, create a new Ref instance and pass that in as the value of the prop:

const myVideoRef = useRef();
...
<CldVideoPlayer videoRef={myVideoRef} ... />

Basic Usage Transformations