Skip to content
Astro Cloudinary

Configuring CldVideoPlayer

Required Props

The basic props required to use CldVideoPlayer include:

Prop Type Required Example
height string | number Yes 1080 Player Height
src string Yes "videos/publicid" Cloudinary Public ID
width string | number Yes 1920 Player Width

Customization

The CldVideoPlayer component allows you to customize your player opting into more advanced capabilities like an AI-based highlights graph and simpler options like configuring the color scheme.

Prop Type Default Example
aiHighlightsGraph boolean false true More Info
bigPlayButton boolean | string true "init" More Info
chaptersButton boolean false true More Info
colors object See Colors Below See Colors Below More Info
controlBar object - More Info
controls boolean true true More Info
floatingWhenNotVisible string - "left" More Info
fluid boolean true false More Info
fontFace string Fira Sans `"Source Serif Pro"` More Info
hideContextMenu boolean false true More Info
interactionAreas any - More Info
logo boolean | object - See Logo Below More Info
playbackRates array - More Info
playlistWidget object - More Info
poster string/object - See Poster Below More Info
posterOptions object - More Info
showJumpControls boolean - More Info
showLogo boolean true false More Info
seekThumbnails boolean true false More Info

Colors

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

Prop Type Default Example
accent string "#FF620C" "#FF00FF" More Info
base string "#000000" "#FF00FF" More Info
text string "#FFFFFF" "#FF00FF" More Info

Learn more about the color scheme options and how they’re used on the Cloudinary docs.

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 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 Type Default Example
imageUrl string https://.../image.jpg More Info
onClickUrl string https://spacejelly.dev More Info

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.

Transformations

Prop Type Default Example
sourceTransformation object - More Info
transformation object | array | string - { width: 200, height: 200, crop: 'fill' } More Info

Advanced

Ads & Analytics

Prop Type Default Example
ads object - More Info
analytics boolean false true More Info
allowUsageReport boolean true false More Info
cloudinaryAnalytics boolean true false More Info

Configuration & Delivery

Prop Type Default Example
chapters object - { 0: "Chapter 1" } More Info
class string my-video-player Additional class names added to the video container.
config object - { url: { cloudName: 'spacejelly' } } More Info
cname string spacejelly.dev More Info
id string my-video Player instance and DOM ID
preload string `auto` More Info
privateCdn boolean true More Info
secureDistribution string spacejelly.dev More Info
sourceTypes Array<string> - ['hls'] More Info
queryParams string/object {myParam: 'value'} More Info
videoJS object - More Info

config

Allows configuration for the Cloudinary environment.

Examples

config={{
  cloud: {
    cloudName: '<Your Cloud Name>',
  }
}}

cname

The custom domain name (CNAME) to use for building URLs, requires secure: false.

Examples

cname="spacejelly.dev"

privateCdn

Set this parameter to true if you are an Advanced plan user with a private CDN distribution

Examples

privateCdn={true}

secureDistribution

The custom domain name (CNAME) to use for building URLs, requires secure: true.

Examples

secureDistribution="spacejelly.dev"

queryParams

Query parameters to append to video URL.

Examples

queryParams={{
  myParam: 'value'
}}

videoJS

Enables you to access all underlying capabilities of the VideoJS API.

Learn more on the VideoJS Docs.

Events

Event handlers allow you to hook into different player events when they occur.

The events are triggered as global custom events which you can assign an event listener to the player.

Examples

<CldVideoPlayer {...props} id="video-player-events" />


<script>
const videoPlayer = document.querySelector(`#video-player-events`);


if ( videoPlayer ) {
  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', ((e: CustomEvent<{ detail: {} }>) => {
    console.log('cldvideoplayer:loadedmetadata', e.detail)
  }) as EventListener);
}
</script>

Localization

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

Prop Type Default Example
language string - pt More Info
languages object - { "Play Video": "Reproduzir vídeo" } More Info

Uses Video.js JSON format for localization customization: https://videojs.com/guides/languages/#json-format

Player Behavior

Prop Type Default Example
autoplay string | boolean "never" "on-scroll", true More Info
autoShowRecommendations boolean false true More Info
loop boolean false true More Info
maxTries number 3 5 More Info
muted boolean false true More Info
pictureInPictureToggle boolean false true More Info
playedEventPercents Array<number> [25, 50, 75, 100] [20, 40, 60, 80, 100] More Info
playedEventTimes Array<number> | null null [30, 60] More Info
playsinline boolean false true More Info
videoTimeout number 55000 60000 More Info
withCredentials boolean false true More Info