<CldVideoPlayer />
Configuration

CldVideoPlayer Configuration

General Props

Prop NameTypeDefaultDescriptionExample
classNamestring-Additional class names added to the video container"my-video-player"
heightstring/number-Required: Player height1080
idstring-Video instance ID, defaults to src value"my-video"
logoboolean/objectSee BelowLogo to display in Player UISee Logo Below
onDataLoadFunction-Triggered when video metadata is loadedSee Events Below
onErrorFunction-Triggered on video errorSee Events Below
onMetadataLoadFunction-Triggered when video data is loadedSee Events Below
onPauseFunction-Triggered on video pauseSee Events Below
onPlayFunction-Triggered on video playSee Events Below
onEndedFunction-Triggered when video has ended playSee Events Below
playerRefRef-React ref to access Player instanceSee Refs Below
posterstring/object-Customize the video's posterSee Poster Below
srcstring-Required: Video public ID"videos/my-video"
videoRefRef-React ref to access video elementSee Refs Below
widthstring/number-Required: Player width1920

Player visuals Props

Prop NameTypeDefaultDescriptionExample
aiHighlightsGraphbooleanfalseCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
bigPlayButtonboolean/stringtrueCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
colorsobjectSee belowPlayer chrome colorsSee Colors Below
controlBarobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
controlsbooleantrueShow player controlstrue
floatingWhenNotVisiblestring-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
fluidboolean-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
fontFacestring-Player UI font. Uses Google Fonts."Source Serif Pro"
hideContextMenubooleanfalseCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
interactionAreasany-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
playbackRatesarray-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
playlistWidgetobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
posterOptionsobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
showJumpControlsboolean-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
showLogobooleatrueShow the Cloudinary logo on Playerfalse
seekThumbnailsbooleantrueCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
videoJSobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs

Player Behavior Props

Prop NameTypeDefaultDescriptionExample
autoplaystring/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
autoShowRecommendationsboolean-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
loopbooleanfalseLoop the videotrue
maxTriesnumber3Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
mutedbooleanfalseLoad muted by defaulttrue
playedEventPercentsarray[25, 50, 75, 100]Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
playedEventTimesarray/nullnullCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
playsinlineboolean-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
videoTimeoutnumber55000Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
withCredentialsboolean-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs

Video Config Props

Prop NameTypeDefaultDescriptionExample
chaptersobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
preloadstringautoCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
publicIdstring-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
sourceTransformationobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
sourceTypesarray-Streaming format['hls']
transformationobject/array-Transformations to apply to the video{ width: 200, height: 200, crop: 'fill' }

Ads And Analytics Props

Prop NameTypeDefaultDescriptionExample
adsobject-Check Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
analyticsbooleanfalseCheck Cloudinary Video Player Api DocsCheck Cloudinary Video Api Docs
allowUsageReportbooleantrueCheck Cloudinary Video Player Api DocsCheck 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 NameTypeDefaultDescriptionExample
cnamestring-The custom domain name (CNAME) to use for building URLs, requires secure: false.mycname.com
privateCdnbooleanfalseSet this parameter to true if you are an Advanced plan user with a private CDN distributiontrue
secureDistributionstring-The custom domain name (CNAME) to use for building URLs, requires secure: true.mycname.com
queryParamsstring/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 NameTypeDefaultDescription
imageUrlstring-Image URL for player logo.
onClickUrlstring-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 NameTypeDefaultDescription
accentstring"#FF620C"Seek bar, volume control and for highlighting interactions.
basestring"#000000"Player controls bar, information bar, central play button, and right-click context menu.
textstring"#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 NameTypeDefaultDescription
languagestring-The language of the player's labels.
languagesobject-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} ... />