The usage

The CldVideoPlayer component helps to embed Cloudinary videos using the Cloudinary Video Player giving you a full customizable experience for your player.

Basic Usage

The basic required props include width, height, and src:

<CldVideoPlayer width="1920" height="1080" src="<Public ID>" />


You can further take advantage of features like customizing your player:

    fontFace="Source Serif Pro"

<script setup lang="ts">
  const colors = {
    accent: "#ff0000",
    base: "#00ff00",
    text: "#0000ff",

Player Events

Or listening to player events for advanced interactions with:

  src="<Cloudinary URL>"
  :onMetadataLoad="({ player }) => console.log(`duration: ${player.duration()}`)"
  :onPause="({ player }) => console.log(`current time: ${player.currentTime()}`)"
Check the browser console after playing and pausing the video for logs that were added to the component.

General Props

Prop NameTypeDefaultDescriptionExample
autoPlaystring"never"When, if, should the video automatically play. See autoplayMode in Video Player docs"on-scroll"
classNamestring-Additional class names added to the video container"my-video-player"
colorsobjectSee belowPlayer chrome colorsSee Colors Below
controlsbooleantrueShow player controlstrue
fontFacestring-Player UI font. Uses Google Fonts."Source Serif Pro"
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
loopbooleanfalseLoop the videotrue
mutedbooleanfalseLoad muted by defaulttrue
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
showLogobooleatrueShow the Cloudinary logo on Playerfalse
srcstring-Required: Video public ID"videos/my-video"
transformationobject/array-Transformations to apply to the video{ width: 200, height: 200, crop: 'fill' }
versionstring"1.9.4"Cloudinary Video Player version"1.9.4"
videoRefRef-React ref to access video elementSee Refs Below
widthstring/number-Required: Player width1920

Colors Prop

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.

Event Props

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:

  :onPause="({ player }) => console.log(`current time: ${player.currentTime()}`)"

Logo Prop

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

logo defaults to true, showing the Cloudinary logo and linking to 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.

Ref Props

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 as ref to the CldVideoPlayer component:

<script setup lang="ts">
const cldVideoPlayerRef = ref();

// will output { playerRef, videoRef }

  <CldVideoPlayer ref="cldVideoPlayerRef" ... />