Cloudinary Logo Cloudinary Docs Docs
  • Programmable Media
    • Get Started
    • Guides
    • References
    • SDKs
    • Release Notes
  • Digital Asset Management
    • Get Started
    • User Guides
    • Admin Guides
    • Release Notes
  • More Products
    • Integrations Add Cloudinary capabilities to your tech stack apps and platforms
    • MediaFlows Low-code workflow automation for images and videos
    • Dimensions (Beta) Create and deliver engaging 3D immersive experiences
    • FinalTouch (Early Access) AI-powered virtual photoshoot and image creation for eCommerce
  • Resources
    • Blog
    • Training
    • Support
    • Community
    • Podcasts
    • Demos
    • Roadmap
    • Additional Resources
  • Pricing
Light theme
Dark theme
Device default
Go to Console
sign up for free
  • Get Started
    • Programmable Media overview
    • Developer onboarding guide
      • 5-step walkthrough
      • Service introduction
      • Onboarding FAQ
      • Enterprise onboarding FAQ
      • Migration guide
      • Glossary
    • SDK quick starts
    • Try it!
      • Code explorers
      • Feature demos
      • Postman collections
    • Video tutorial library
      • Programmatic asset management
      • Optimization and delivery
      • Transformations
      • Dev Hints on YouTube
  • Guides
    • Upload
      • Uploading assets
      • Customizing uploads
      • Client-side uploading
      • Upload presets
      • Upload widget
    • Transform and customize
      • Image transformations
      • Video transformations
      • Eager and incoming transformations
      • Media Editor widget
      • How are transformations counted?
      • Add-ons
    • Optimize and deliver
      • Optimization overview
      • Image optimization
      • Video and audio optimization
      • Responsive images
      • Deliver remote media files
      • Paged and layered media
      • Media access methods
      • CDN delivery options
      • Product Gallery widget
      • Add-ons
    • Manage and analyze
      • Basic management
      • Search for assets
      • Custom metadata
      • Analyze assets
      • Moderate assets
      • Webhook notifications
      • Create assets
      • Advanced asset management
      • Add-ons
    • Video APIs
      • Video best practices
      • Video Player
      • Video transcription
      • Video analytics
      • Live streaming (Beta)
    • AI in action
    • Native mobile
    • Add-ons
      • Advanced Facial Attributes Detection
      • Amazon Rekognition AI Moderation
      • Amazon Rekognition Video Moderation
      • Amazon Rekognition Auto Tagging
      • Amazon Rekognition Celebrity Detection
      • Aspose Document Conversion
      • Cloudinary AI Background Removal
      • Cloudinary AI Content Analysis
      • Cloudinary AI Vision (Beta)
      • Cloudinary Duplicate Image Detection
      • Google AI Video Moderation
      • Google AI Video Transcription
      • Google Auto Tagging
      • Google Automatic Video Tagging
      • Google Translation
      • Imagga Auto Tagging
      • Imagga Crop and Scale
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Provisioning API
    • Analyze API (Beta)
    • Live streaming API (Beta)
    • Cloudinary CLI
    • SDK references
      • Transformation Builder reference
      • React SDK reference
      • Vue.js SDK reference
      • JavaScript SDK reference
      • Angular SDK reference
      • PHP SDK reference
      • Go SDK reference
      • Dart SDK reference
      • Flutter SDK reference
    • Postman collections
    • Upload Widget API
    • Product Gallery API
    • Media Editor API
    • Video Player API
  • SDKs
    • Backend SDKs
      • Node.js SDK
      • Python SDK
      • PHP SDK
      • Java SDK
      • Ruby/Rails SDK
      • .NET SDK
      • Go SDK
      • Dart SDK
      • PHP SDK (Legacy)
    • Frontend SDKs
      • React SDK
      • Vue.js SDK
      • Angular SDK
      • JavaScript SDK
      • jQuery SDK
      • React SDK (Legacy)
      • Vue.js SDK (Legacy)
      • Angular SDK (Legacy)
      • JavaScript SDK (Legacy)
    • Mobile SDKs
      • iOS SDK
      • Android SDK
      • Flutter SDK
      • React Native SDK
      • Kotlin SDK
    • Community-developed libraries
      • Next.js
      • Laravel
      • NuxtJS
      • Svelte
      • Gatsby
      • Netlify
      • Drupal
  • Release Notes
    • Latest: August 12, 2024
    • June 27, 2024
    • May 31, 2024
    • April 16, 2024
    • Previous releases
      • February 28, 2024
      • January 03, 2024
      • November 13, 2023
      • October 26, 2023
      • September 21, 2023
      • August 15, 2023
      • July 13, 2023
      • June 19, 2023
      • May 16, 2023
      • Apr 04, 2023
      • Feb 21, 2023
      • Dec 27, 2022
  • Get Started
    • Programmable Media overview
    • Developer onboarding guide
      • 5-step walkthrough
      • Service introduction
      • Onboarding FAQ
        • Enterprise onboarding FAQ
        • Migration guide
        • Glossary
      • SDK quick starts
      • Try it!
        • Code explorers
        • Feature demos
        • Postman collections
      • Video tutorial library
        • Programmatic asset management
          • Programmatic upload
            • Upload programmatically
            • Create upload presets
            • Auto upload
            • Auto-tag assets
            • Moderate images with AI
            • Upload images in Flutter
            • Upload images in Node.js
            • Upload multiple files in Node.js
            • Upload videos in Node.js
            • Upload images in Python
            • Upload videos in Python
            • Upload assets in a React app
            • Upload assets in a Next.js app
            • Upload assets with Server Actions
            • Upload assets in a SvelteKit app
            • Upload assets in a Remix app
            • Use webhooks to remove backgrounds
          • Interaction with Cloudinary APIs
            • Generate upload signature
            • Postman collections introduction
          • Cloudinary SDKs
            • Find your credentials
            • Configure the JavaScript SDK
            • Configure the React SDK
            • Configure the Flutter SDK
            • Configure Svelte Cloudinary
            • Configure the Javascript SDK in Svelte
            • Configure the Node.js SDK
            • Configure the Python SDK
            • Configure the Vue.js SDK
            • Configure the Next.js SDK
            • List images in Next.js
            • Captioning on upload with Node.js
            • Delete assets with Node.js
            • Manage images in a Django app
          • Cloudinary CLI
            • Get started with the CLI
            • Scripting with the CLI
            • Get creative with the CLI
            • Upload with the CLI
          • Widgets
            • Upload Widget
            • Product Gallery
            • Product Gallery in React
            • Product Gallery accessibility
          • Administration
            • Enable automatic backups
            • Restore asset versions
            • Restore deleted assets
        • Optimization and delivery
          • Programmatic optimization
            • Optimization tips
            • Optimize videos in React
            • Transform and optimize images in Svelte
            • Optimize videos in Next.js
            • Optimize Images with Nuxt Cloudinary
            • Optimize Images in SolidJS with Cloudinary
            • Optimize images in Flutter
          • Programmatic delivery
            • Deliver images with the Next.js Image component
            • Deliver images with the Nuxt Image component
            • Diagnosing error codes
          • Video Player
            • Video Player in React
            • Video Player in Next.js
            • Video Player in HTML
        • Transformations
          • Get started with transformations
            • Transformation basics
            • Transformation Builder
            • Gravity-based crops for images
            • Enhance and restore images
            • Transformation overlays
            • Content-aware image cropping
            • Content-aware video cropping
            • Convert videos to animated images
          • Advanced transformation features
            • Text overlay transformations
            • Complex transformations
            • Named transformations
            • Named transformations using TX Builder
            • Advanced image components
            • Trim videos in Node.js
            • Splice videos in Node.js
            • Zoompan effect
            • Video transformations
            • Crop and resize images in React
            • Crop and resize videos in React
            • Remove backgrounds and add drop shadows
            • AI generative fill in Next.js
            • Color accessibility in JavaScript
          • Transformations for social media
            • Social media image cards in Next.js
            • Social media image cards in Svelte
        • Dev Hints on YouTube
    • Guides
      • Upload
        • Uploading assets
        • Customizing uploads
        • Client-side uploading
        • Upload presets
        • Upload widget
      • Transform and customize
        • Image transformations
          • Image transformations overview
          • Resizing and cropping
          • Placing layers on images
          • Effects and enhancements
          • Face-detection based transformations
          • Animated images
          • Transformations on 3D models
          • Conditional transformations
          • User-defined variables and arithmetic transformations
          • Custom functions
        • Video transformations
          • Video transformations overview
          • Resizing and cropping
          • Trimming and concatenating
          • Placing layers on videos
          • Effects and enhancements
          • Audio transformations
          • Advanced video transformations
            • Converting videos to animated images
            • Conditional transformations
            • User-defined variables and arithmetic transformations
        • Eager and incoming transformations
        • Media Editor widget
        • How are transformations counted?
        • Add-ons
      • Optimize and deliver
        • Optimization overview
        • Image optimization
        • Video and audio optimization
          • Video optimization
          • Adaptive bitrate streaming
          • Audio optimization
        • Responsive images
          • Using HTML and dynamic image transformations
          • Using JavaScript frontend frameworks
          • Using the cloudinary-core JS library
          • Using client hints
        • Deliver remote media files
          • Social media profile pictures
        • Paged and layered media
        • Media access methods
        • CDN delivery options
        • Product Gallery widget
        • Add-ons
      • Manage and analyze
        • Basic management
          • Media Explorer
          • List assets
          • Update assets
          • Delete assets
          • Rename assets
          • Relate assets
        • Search for assets
          • Search API method
          • Cacheable search URLs
          • Visual Search
          • Media Explorer search
          • Search expressions
        • Custom metadata
          • Tags
          • Contextual metadata
          • Structured metadata
            • Conditional metadata rules
        • Analyze assets
          • Image quality analysis
          • Accessibility analysis
          • Semantic data extraction
          • Media Inspector (Labs)
          • Analyze API (Beta)
        • Moderate assets
        • Webhook notifications
        • Create assets
          • Animated images
          • Videos
          • Archives
          • Sprites
          • Image collages
          • PDF files from images
          • Images from text
        • Advanced asset management
          • Signatures
            • Authentication signatures
            • Notification signatures
            • Delivery URL signatures
            • Response signatures
          • Backups and version management
          • Invalidate cached assets
          • Account usage data
          • Folder modes
        • Add-ons
      • Video APIs
        • Video best practices
          • Social media videos
        • Video Player
          • Video Player features
          • Installation and setup
          • How to embed the Video Player
          • Video Player customization
          • Playlists and recommendations
          • HLS and MPEG-DASH
          • Video Player advanced features
            • Events and analytics
            • Video ads and monetization
            • Shoppable Video
            • Interactive Video (Beta)
          • Video Player API reference
        • Video transcription
        • Video analytics
        • Live streaming (Beta)
          • Live streaming API reference
          • Simulated live streaming
      • AI in action
      • Native mobile
      • Add-ons
        • Advanced Facial Attributes Detection
        • Amazon Rekognition AI Moderation
        • Amazon Rekognition Video Moderation
        • Amazon Rekognition Auto Tagging
        • Amazon Rekognition Celebrity Detection
        • Aspose Document Conversion
        • Cloudinary AI Background Removal
        • Cloudinary AI Content Analysis
        • Cloudinary AI Vision (Beta)
        • Cloudinary Duplicate Image Detection
        • Google AI Video Moderation
        • Google AI Video Transcription
        • Google Auto Tagging
        • Google Automatic Video Tagging
        • Google Translation
        • Imagga Auto Tagging
        • Imagga Crop and Scale
        • Perception Point Malware Detection
        • Microsoft Azure Video Indexer
        • OCR Text Detection and Extraction
        • Pixelz - Remove the Background
        • URL2PNG Website Screenshots
        • VIESUS™ Automatic Image Enhancement
        • WebPurify Image Moderation
    • References
      • Transformation URL API
      • Upload API
      • Admin API
      • Provisioning API
      • Analyze API (Beta)
      • Live streaming API (Beta)
      • Cloudinary CLI
      • SDK references
        • Transformation Builder reference
        • React SDK reference
        • Vue.js SDK reference
        • JavaScript SDK reference
        • Angular SDK reference
        • PHP SDK reference
        • Go SDK reference
        • Dart SDK reference
        • Flutter SDK reference
      • Postman collections
      • Upload Widget API
      • Product Gallery API
      • Media Editor API
      • Video Player API
    • SDKs
      • Backend SDKs
        • Node.js SDK
          • Node.js introduction
          • Node.js quick start
          • Node.js image and video upload
          • Node.js image transformations
          • Node.js video transformations
          • Node.js asset management
          • Node.js video tutorials
        • Python SDK
          • Python introduction
          • Python quick start
          • Python image and video upload
          • Python image transformations
          • Python video transformations
          • Python asset management
          • Python sample projects
          • Python video tutorials
        • PHP SDK
          • PHP introduction
          • PHP quick start
          • PHP image and video upload
          • PHP image transformations
          • PHP video transformations
          • PHP asset management
          • PHP Management reference
          • PHP Transformation reference
        • Java SDK
          • Java introduction
          • Java quick start
          • Java image and video upload
          • Java image transformations
          • Java video transformations
          • Java asset management
        • Ruby/Rails SDK
          • Ruby/Rails introduction
          • Ruby/Rails quick start
          • Ruby/Rails image and video upload
          • Ruby/Rails image transformations
          • Ruby/Rails video transformations
          • Ruby/Rails asset management
          • CarrierWave integration
          • Attachinary integration
          • Active Storage integration
        • .NET SDK
          • .NET introduction
          • .NET quick start
          • .NET image and video upload
          • .NET image transformations
          • .NET video transformations
          • .NET asset management
        • Go SDK
          • Go introduction
          • Go quick start
          • Go image and video upload
          • Go media transformations
          • Go asset management
          • Go SDK reference
        • Dart SDK
          • Dart introduction
          • Dart quick start
          • Dart image and video upload
          • Dart media transformations
          • Dart SDK reference
        • PHP SDK (Legacy)
          • PHP introduction
          • PHP image and video upload
          • PHP image transformations
          • PHP video transformations
          • PHP asset management
          • PHP migration guide
      • Frontend SDKs
        • React SDK
          • React introduction
          • React quick start
          • React image and video upload
          • React image transformations
          • React video transformations
          • React sample projects
          • React video tutorials
          • React SDK reference
          • Transformation Builder reference
        • Vue.js SDK
          • Vue.js introduction
          • Vue.js quick start
          • Vue.js image and video upload
          • Vue.js image transformations
          • Vue.js video transformations
          • Vue.js sample projects
          • Vue.js video tutorials
          • Vue.js SDK reference
          • Transformation Builder reference
        • Angular SDK
          • Angular introduction
          • Angular quick start
          • Angular image and video upload
          • Angular image transformations
          • Angular video transformations
          • Angular sample projects
          • Angular SDK reference
          • Transformation Builder reference
        • JavaScript SDK
          • JavaScript introduction
          • JavaScript quick start
          • JavaScript image and video upload
          • JavaScript image transformations
          • JavaScript video transformations
          • JavaScript sample projects
          • JavaScript video tutorials
          • JavaScript SDK reference
          • Transformation Builder reference
        • jQuery SDK
          • jQuery introduction
          • jQuery image and video upload
          • jQuery image transformations
          • jQuery video transformations
        • React SDK (Legacy)
          • React introduction
          • React image and video upload
          • React image transformations
          • React video transformations
          • React migration guide
        • Vue.js SDK (Legacy)
          • Vue.js introduction
          • Vue.js image and video upload
          • Vue.js image transformations
          • Vue.js video transformations
          • Vue.js migration guide
        • Angular SDK (Legacy)
          • Angular introduction
          • Angular image and video upload
          • Angular image transformations
          • Angular video transformations
          • Angular migration guide
        • JavaScript SDK (Legacy)
          • JavaScript introduction
          • JavaScript image and video upload
          • JavaScript image transformations
          • JavaScript video transformations
          • JavaScript migration guide
      • Mobile SDKs
        • iOS SDK
          • iOS introduction
          • iOS quick start
          • iOS image and video upload
          • iOS image transformations
          • iOS video transformations
          • iOS video player
          • iOS sample projects
        • Android SDK
          • Android introduction
          • Android image and video upload
          • Android image transformations
          • Android video transformations
          • Android video player
          • Android sample projects
        • Flutter SDK
          • Flutter introduction
          • Flutter quick start
          • Flutter image and video upload
          • Flutter media transformations
          • Flutter video player
          • Flutter video tutorials
          • Dart-based cloudinary_url_gen package reference
          • Flutter SDK reference
        • React Native SDK
          • React Native introduction
          • React Native image and video upload
          • React Native image transformations
          • React Native video transformations
          • React Native video player
        • Kotlin SDK
          • Kotlin media transformations
      • Community-developed libraries
        • Next.js
        • Laravel
        • NuxtJS
        • Svelte
        • Gatsby
        • Netlify
        • Drupal
    • Release Notes
      • Latest: August 12, 2024
      • June 27, 2024
      • May 31, 2024
      • April 16, 2024
      • Previous releases
        • February 28, 2024
        • January 03, 2024
        • November 13, 2023
        • October 26, 2023
        • September 21, 2023
        • August 15, 2023
        • July 13, 2023
        • June 19, 2023
        • May 16, 2023
        • Apr 04, 2023
        • Feb 21, 2023
        • Dec 27, 2022
    Programmable Media
    • Get Started
    • Guides
    • References
    • SDKs
    • Release Notes
    Digital Asset Management
    • Get Started
    • User Guides
    • Admin Guides
    • Release Notes
  • More Products
      More Products
      Integrations
      Add Cloudinary capabilities to your tech stack apps and platforms
      MediaFlows
      Low-code workflow automation for images and videos
      Dimensions (Beta)
      Create and deliver engaging 3D immersive experiences
      FinalTouch (Early Access)
      AI-powered virtual photoshoot and image creation for eCommerce
  • Resources
      Resources
      Blog
      Training
      Support
      Community
      Podcasts
      Demos
      Roadmap
      Additional Resources
  • Pricing
    sign up for free
    Programmable Media
    Menu
    • Get Started
      • Programmable Media overview
      • Developer onboarding guide
        • 5-step walkthrough
        • Service introduction
        • Onboarding FAQ
          • Enterprise onboarding FAQ
          • Migration guide
          • Glossary
        • SDK quick starts
        • Try it!
          • Code explorers
          • Feature demos
          • Postman collections
        • Video tutorial library
          • Programmatic asset management
            • Programmatic upload
              • Upload programmatically
              • Create upload presets
              • Auto upload
              • Auto-tag assets
              • Moderate images with AI
              • Upload images in Flutter
              • Upload images in Node.js
              • Upload multiple files in Node.js
              • Upload videos in Node.js
              • Upload images in Python
              • Upload videos in Python
              • Upload assets in a React app
              • Upload assets in a Next.js app
              • Upload assets with Server Actions
              • Upload assets in a SvelteKit app
              • Upload assets in a Remix app
              • Use webhooks to remove backgrounds
            • Interaction with Cloudinary APIs
              • Generate upload signature
              • Postman collections introduction
            • Cloudinary SDKs
              • Find your credentials
              • Configure the JavaScript SDK
              • Configure the React SDK
              • Configure the Flutter SDK
              • Configure Svelte Cloudinary
              • Configure the Javascript SDK in Svelte
              • Configure the Node.js SDK
              • Configure the Python SDK
              • Configure the Vue.js SDK
              • Configure the Next.js SDK
              • List images in Next.js
              • Captioning on upload with Node.js
              • Delete assets with Node.js
              • Manage images in a Django app
            • Cloudinary CLI
              • Get started with the CLI
              • Scripting with the CLI
              • Get creative with the CLI
              • Upload with the CLI
            • Widgets
              • Upload Widget
              • Product Gallery
              • Product Gallery in React
              • Product Gallery accessibility
            • Administration
              • Enable automatic backups
              • Restore asset versions
              • Restore deleted assets
          • Optimization and delivery
            • Programmatic optimization
              • Optimization tips
              • Optimize videos in React
              • Transform and optimize images in Svelte
              • Optimize videos in Next.js
              • Optimize Images with Nuxt Cloudinary
              • Optimize Images in SolidJS with Cloudinary
              • Optimize images in Flutter
            • Programmatic delivery
              • Deliver images with the Next.js Image component
              • Deliver images with the Nuxt Image component
              • Diagnosing error codes
            • Video Player
              • Video Player in React
              • Video Player in Next.js
              • Video Player in HTML
          • Transformations
            • Get started with transformations
              • Transformation basics
              • Transformation Builder
              • Gravity-based crops for images
              • Enhance and restore images
              • Transformation overlays
              • Content-aware image cropping
              • Content-aware video cropping
              • Convert videos to animated images
            • Advanced transformation features
              • Text overlay transformations
              • Complex transformations
              • Named transformations
              • Named transformations using TX Builder
              • Advanced image components
              • Trim videos in Node.js
              • Splice videos in Node.js
              • Zoompan effect
              • Video transformations
              • Crop and resize images in React
              • Crop and resize videos in React
              • Remove backgrounds and add drop shadows
              • AI generative fill in Next.js
              • Color accessibility in JavaScript
            • Transformations for social media
              • Social media image cards in Next.js
              • Social media image cards in Svelte
          • Dev Hints on YouTube
      • Guides
        • Upload
          • Uploading assets
          • Customizing uploads
          • Client-side uploading
          • Upload presets
          • Upload widget
        • Transform and customize
          • Image transformations
            • Image transformations overview
            • Resizing and cropping
            • Placing layers on images
            • Effects and enhancements
            • Face-detection based transformations
            • Animated images
            • Transformations on 3D models
            • Conditional transformations
            • User-defined variables and arithmetic transformations
            • Custom functions
          • Video transformations
            • Video transformations overview
            • Resizing and cropping
            • Trimming and concatenating
            • Placing layers on videos
            • Effects and enhancements
            • Audio transformations
            • Advanced video transformations
              • Converting videos to animated images
              • Conditional transformations
              • User-defined variables and arithmetic transformations
          • Eager and incoming transformations
          • Media Editor widget
          • How are transformations counted?
          • Add-ons
        • Optimize and deliver
          • Optimization overview
          • Image optimization
          • Video and audio optimization
            • Video optimization
            • Adaptive bitrate streaming
            • Audio optimization
          • Responsive images
            • Using HTML and dynamic image transformations
            • Using JavaScript frontend frameworks
            • Using the cloudinary-core JS library
            • Using client hints
          • Deliver remote media files
            • Social media profile pictures
          • Paged and layered media
          • Media access methods
          • CDN delivery options
          • Product Gallery widget
          • Add-ons
        • Manage and analyze
          • Basic management
            • Media Explorer
            • List assets
            • Update assets
            • Delete assets
            • Rename assets
            • Relate assets
          • Search for assets
            • Search API method
            • Cacheable search URLs
            • Visual Search
            • Media Explorer search
            • Search expressions
          • Custom metadata
            • Tags
            • Contextual metadata
            • Structured metadata
              • Conditional metadata rules
          • Analyze assets
            • Image quality analysis
            • Accessibility analysis
            • Semantic data extraction
            • Media Inspector (Labs)
            • Analyze API (Beta)
          • Moderate assets
          • Webhook notifications
          • Create assets
            • Animated images
            • Videos
            • Archives
            • Sprites
            • Image collages
            • PDF files from images
            • Images from text
          • Advanced asset management
            • Signatures
              • Authentication signatures
              • Notification signatures
              • Delivery URL signatures
              • Response signatures
            • Backups and version management
            • Invalidate cached assets
            • Account usage data
            • Folder modes
          • Add-ons
        • Video APIs
          • Video best practices
            • Social media videos
          • Video Player
            • Video Player features
            • Installation and setup
            • How to embed the Video Player
            • Video Player customization
            • Playlists and recommendations
            • HLS and MPEG-DASH
            • Video Player advanced features
              • Events and analytics
              • Video ads and monetization
              • Shoppable Video
              • Interactive Video (Beta)
            • Video Player API reference
          • Video transcription
          • Video analytics
          • Live streaming (Beta)
            • Live streaming API reference
            • Simulated live streaming
        • AI in action
        • Native mobile
        • Add-ons
          • Advanced Facial Attributes Detection
          • Amazon Rekognition AI Moderation
          • Amazon Rekognition Video Moderation
          • Amazon Rekognition Auto Tagging
          • Amazon Rekognition Celebrity Detection
          • Aspose Document Conversion
          • Cloudinary AI Background Removal
          • Cloudinary AI Content Analysis
          • Cloudinary AI Vision (Beta)
          • Cloudinary Duplicate Image Detection
          • Google AI Video Moderation
          • Google AI Video Transcription
          • Google Auto Tagging
          • Google Automatic Video Tagging
          • Google Translation
          • Imagga Auto Tagging
          • Imagga Crop and Scale
          • Perception Point Malware Detection
          • Microsoft Azure Video Indexer
          • OCR Text Detection and Extraction
          • Pixelz - Remove the Background
          • URL2PNG Website Screenshots
          • VIESUS™ Automatic Image Enhancement
          • WebPurify Image Moderation
      • References
        • Transformation URL API
        • Upload API
        • Admin API
        • Provisioning API
        • Analyze API (Beta)
        • Live streaming API (Beta)
        • Cloudinary CLI
        • SDK references
          • Transformation Builder reference
          • React SDK reference
          • Vue.js SDK reference
          • JavaScript SDK reference
          • Angular SDK reference
          • PHP SDK reference
          • Go SDK reference
          • Dart SDK reference
          • Flutter SDK reference
        • Postman collections
        • Upload Widget API
        • Product Gallery API
        • Media Editor API
        • Video Player API
      • SDKs
        • Backend SDKs
          • Node.js SDK
            • Node.js introduction
            • Node.js quick start
            • Node.js image and video upload
            • Node.js image transformations
            • Node.js video transformations
            • Node.js asset management
            • Node.js video tutorials
          • Python SDK
            • Python introduction
            • Python quick start
            • Python image and video upload
            • Python image transformations
            • Python video transformations
            • Python asset management
            • Python sample projects
            • Python video tutorials
          • PHP SDK
            • PHP introduction
            • PHP quick start
            • PHP image and video upload
            • PHP image transformations
            • PHP video transformations
            • PHP asset management
            • PHP Management reference
            • PHP Transformation reference
          • Java SDK
            • Java introduction
            • Java quick start
            • Java image and video upload
            • Java image transformations
            • Java video transformations
            • Java asset management
          • Ruby/Rails SDK
            • Ruby/Rails introduction
            • Ruby/Rails quick start
            • Ruby/Rails image and video upload
            • Ruby/Rails image transformations
            • Ruby/Rails video transformations
            • Ruby/Rails asset management
            • CarrierWave integration
            • Attachinary integration
            • Active Storage integration
          • .NET SDK
            • .NET introduction
            • .NET quick start
            • .NET image and video upload
            • .NET image transformations
            • .NET video transformations
            • .NET asset management
          • Go SDK
            • Go introduction
            • Go quick start
            • Go image and video upload
            • Go media transformations
            • Go asset management
            • Go SDK reference
          • Dart SDK
            • Dart introduction
            • Dart quick start
            • Dart image and video upload
            • Dart media transformations
            • Dart SDK reference
          • PHP SDK (Legacy)
            • PHP introduction
            • PHP image and video upload
            • PHP image transformations
            • PHP video transformations
            • PHP asset management
            • PHP migration guide
        • Frontend SDKs
          • React SDK
            • React introduction
            • React quick start
            • React image and video upload
            • React image transformations
            • React video transformations
            • React sample projects
            • React video tutorials
            • React SDK reference
            • Transformation Builder reference
          • Vue.js SDK
            • Vue.js introduction
            • Vue.js quick start
            • Vue.js image and video upload
            • Vue.js image transformations
            • Vue.js video transformations
            • Vue.js sample projects
            • Vue.js video tutorials
            • Vue.js SDK reference
            • Transformation Builder reference
          • Angular SDK
            • Angular introduction
            • Angular quick start
            • Angular image and video upload
            • Angular image transformations
            • Angular video transformations
            • Angular sample projects
            • Angular SDK reference
            • Transformation Builder reference
          • JavaScript SDK
            • JavaScript introduction
            • JavaScript quick start
            • JavaScript image and video upload
            • JavaScript image transformations
            • JavaScript video transformations
            • JavaScript sample projects
            • JavaScript video tutorials
            • JavaScript SDK reference
            • Transformation Builder reference
          • jQuery SDK
            • jQuery introduction
            • jQuery image and video upload
            • jQuery image transformations
            • jQuery video transformations
          • React SDK (Legacy)
            • React introduction
            • React image and video upload
            • React image transformations
            • React video transformations
            • React migration guide
          • Vue.js SDK (Legacy)
            • Vue.js introduction
            • Vue.js image and video upload
            • Vue.js image transformations
            • Vue.js video transformations
            • Vue.js migration guide
          • Angular SDK (Legacy)
            • Angular introduction
            • Angular image and video upload
            • Angular image transformations
            • Angular video transformations
            • Angular migration guide
          • JavaScript SDK (Legacy)
            • JavaScript introduction
            • JavaScript image and video upload
            • JavaScript image transformations
            • JavaScript video transformations
            • JavaScript migration guide
        • Mobile SDKs
          • iOS SDK
            • iOS introduction
            • iOS quick start
            • iOS image and video upload
            • iOS image transformations
            • iOS video transformations
            • iOS video player
            • iOS sample projects
          • Android SDK
            • Android introduction
            • Android image and video upload
            • Android image transformations
            • Android video transformations
            • Android video player
            • Android sample projects
          • Flutter SDK
            • Flutter introduction
            • Flutter quick start
            • Flutter image and video upload
            • Flutter media transformations
            • Flutter video player
            • Flutter video tutorials
            • Dart-based cloudinary_url_gen package reference
            • Flutter SDK reference
          • React Native SDK
            • React Native introduction
            • React Native image and video upload
            • React Native image transformations
            • React Native video transformations
            • React Native video player
          • Kotlin SDK
            • Kotlin media transformations
        • Community-developed libraries
          • Next.js
          • Laravel
          • NuxtJS
          • Svelte
          • Gatsby
          • Netlify
          • Drupal
      • Release Notes
        • Latest: August 12, 2024
        • June 27, 2024
        • May 31, 2024
        • April 16, 2024
        • Previous releases
          • February 28, 2024
          • January 03, 2024
          • November 13, 2023
          • October 26, 2023
          • September 21, 2023
          • August 15, 2023
          • July 13, 2023
          • June 19, 2023
          • May 16, 2023
          • Apr 04, 2023
          • Feb 21, 2023
          • Dec 27, 2022
      • Programmable Media
      • References
      • Product Gallery API

      Product Gallery API reference

      Last updated: Aug-04-2024

      The Product Gallery API reference details all the parameter options, types and ENUMS that you can use when configuring the Product Gallery widget.

      Tips
      • For in-depth information, see the Product Gallery guide.
      • Use the Product Gallery Demo to try out some of the widget customization options.

      Code explorer: Product Gallery widget example

      Try out some sample configuration changes in this JavaScript Product Gallery Sandbox.

      Tip
      For versions of this code explorer in other frameworks, see:
      • React Product Gallery Sandbox
      • Angular Product Gallery Sandbox
      • Vue Product Gallery Sandbox

      Tip
      Enjoy interactive learning? Check out more code explorers!

      On this page:

      • Code explorer: Product Gallery widget example
      • Parameters
      • Types
      • ENUMs
      • Instance methods
      • Events

      Parameters

      The following tables list all available parameters (options) for creating and initializing a Product Gallery widget with the galleryWidget method:

      • Required parameters
      • Widget parameters
      • Main viewer parameters
      • Carousel parameters
      • Navigation parameters

      Important

      Besides for the required parameters, only include other parameters in order to override their default values.

      For example, to initialize a new widget that is populated with all images that have the "bag" tag:

      Required parameters

      The following parameters are required when initializing the Product Gallery widget:

      Parameter Type Description
      cloudName string Your Cloudinary product environment cloud name.
      Example: "demo"
      container string selector or DOM Element The containing element on the page for the Product Gallery widget.
      Examples:
      "#my-widget-container"
      document.getElementById("my-widget-container");
      mediaAssets Asset[] or PublicID[] Populates the widget with all the media assets given as an array of assets. The individual assets in the array can be described either by an Asset object or by a PublicID string (as a shortcut for images only).
      Example (all images tagged with 'shirt' + a video with the PublicId of 'shirt-vid' + an image with the PublicId of 'shirt-1'):
      [{ tag: "shirt" }, {publicId: "shirt-vid", mediaType: "video"}, "shirt-1"]

      Widget parameters

      Parameter Type Description
      analytics boolean Whether to update the Google Tag Manager's dataLayer array whenever an event is triggered (requires Google Tag Manager integrated on the page).
      displayProps DisplayProps Sets the display properties for the widget.
      focus boolean Whether to set focus on the widget when it renders (to ease keyboard navigation) or only after selecting the widget. Default: false
      loaderProps LoaderProps An object that defines the loading spinner properties to override.
      placeholderImage boolean Whether to load and display a low-quality blurred placeholder image while waiting for the higher quality image, instead of a loading spinner. Default: true
      sort Sort (Deprecated, please use sortProps instead) Determines how to sort (by PublicID) the assets given in the mediaAssets parameter for display in the Product Gallery. Default: asc
      sortProps SortProps An object that defines how to sort the assets for display in the Product Gallery. Default: { source: "public_id", direction: "asc" }
      themeProps ThemeProps An object that defines the theme colors to override.
      viewportBreakpoints BreakpointProps[] An array of breakpoints for the viewport (browser window), together with the Product Gallery configuration parameters to override when the width of the Product Gallery widget is less than the given breakpoint (see Responsive widget for more information).

      Main viewer parameters

      Parameter Type Description
      accessibilityProps AccessibilityProps An object that defines the accessibility properties to override.
      ar3dProps Ar3dProps An object that defines the 3D viewer properties.
      aspectRatio AspectRatio The aspect ratio of the main viewer. Default: "square"
      borderColor Color The color of the main viewer's border. Default: "transparent"
      borderWidth int The width of the main viewer's border in pixels. Default: 0
      imageBreakpoint int The step size for rounding up the width of responsive images in pixels. Default: 100
      videoBreakpoint int The step size for rounding up the width of responsive videos in pixels. Default: 100
      preload String[] An array indicating which media assets should be preloaded into the browser cache when the Product Gallery widget is initialized. Possible values: "image", "video", "spin", "3d". Default: ["image"]
      Note: pass an empty array if you want to preload only the first asset ([]).
      radius int The radius of the main viewer's corners in pixels. Default: 0
      spinProps SpinProps An object that defines the 360 spin set properties to override.
      startIndex int The media asset to initially display in the main viewer when the widget is rendered. Default: 0 (the first asset)
      tipProps TipProps An object that defines the properties to override for the zoom tip, which appears on images and 360 spin sets.
      Relevant only when zoom is set to 'true'.
      transition Transitions The effect to apply while transitioning between assets. Default: "slide"
      videoProps VideoProps An object that defines the video display properties to override.
      zoom boolean Whether to activate the zoom functionality for images. Default: true
      zoomProps ZoomProps An object that defines the zoom properties to override.
      Relevant only when zoom is set to 'true'.
      zoomPopupProps ZoomPopupProps An object that defines the backdrop color, opacity and z-index stack order.
      Relevant only when zoomProps: type is set to 'popup'.

      Carousel parameters

      Parameter Type Description
      carouselLocation CarouselLocation The location of the carousel relative to the main viewer. Default: "left"
      carouselOffset int The space between the main viewer and the carousel in pixels. Default: 5
      carouselStyle CarouselStyle The display style of the carousel. Default: "thumbnails"
      indicatorProps IndicatorProps An object that defines the indicator properties to override.
      Relevant only when carouselStyle is set to 'indicators'.
      thumbnailProps ThumbnailProps An object that defines the thumbnail properties to override.
      Relevant only when carouselStyle is set to 'thumbnails'.

      Navigation parameters

      Parameter Type Description
      navigation Navigation The display style of the navigation buttons. Default: "mouseover"
      navigationButtonProps NavigationButtonProps An object that defines the navigation button properties to override.
      navigationOffset int The offset of the navigation buttons from the side of the widget in pixels. Default: 0
      Relevant only when navigationPosition is set to a value of 'offset'.
      navigationPosition NavigationPosition The position of the navigation buttons. Default: "inside"

      Types

      • Asset
      • AccessibilityProps
      • Ar3dProps
      • BreakpointProps
      • Color
      • DisplayProps
      • IndicatorProps
      • LoaderProps
      • NavigationButtonProps
      • SpinProps
      • ThemeProps
      • ThumbnailProps
      • TipProps
      • VideoProps
      • ZoomProps
      • zoomPopupProps

      Asset

      An object identifying either a single media asset or multiple assets: use the publicId parameter to identify a single asset, or use the tag parameter to identify multiple assets of the same mediaType.

      Parameter Type Description
      publicId string A string value representing the identifier that is used for accessing an uploaded media asset. Use this parameter to identify a single resource.
      Example:
      "long-shirt"
      tag string All assets (as given by mediaType) that have the given tag. Use this parameter to identify multiple assets. The assets will be ordered alphanumerically by their PublicID.
      Example:
      "shirt"
      mediaType string The type of media to deliver ("image", "video", "spin" or "3d" ). The default is 'image' if not specified.
      resourceType string Set to "video" if you are delivering an image (mediaType: "image") of an uploaded video asset.
      transformation Object The Cloudinary transformation to apply. Any set of transformation options can be applied in addition to the default transformation parameters, or to override their values.

      To apply this transformation before the default transformation parameters, set prefixed: false in this object.

      thumbnailTransformation Object The Cloudinary transformation to apply to the thumbnail image(s) used in the carousel to represent the media asset. This value overrides the transformation parameter (only for thumbnails) if that is also given.

      To apply this transformation before the default transformation parameters, set prefixed: false in this object.

      altText string The string to use as the Alt accessibility text in the gallery.
      videoPlayerSource Object The Cloudinary Video Player source options to apply to the video.
      Relevant only when the playerType property of the videoProps parameter is set to 'cloudinary'.

      Note
      All transformations use the JavaScript (legacy) syntax. When looking at transformation examples in the rest of the documentation, you can change the JS tab to display the legacy (cloudinary-core) code examples.

      For example:

      AccessibilityProps

      The accessibility properties to override for the widget.

      Parameter Type Description
      mediaAltSource string The source of the string to use as the Alt accessibility text for each of the media assets in the gallery. The value of this property can be one of the following sources:
      - contextual: use the value of a Contextual metadata field for each asset, as given by the key passed in the mediaAltId property.
      - metadata: use the value of a Structured metadata field for each asset as given by the external_id passed in the mediaAltId property.
      - auto: (default) use the order of the asset within the gallery using the template: "Gallery asset n of m".
      mediaAltId string Required when setting the mediaAltSource property as follows:
      For 'contextual' - the key of a Contextual metadata key-value pair (or an empty string to use the default 'alt' key added to every asset).
      OR
      For 'metadata' - the external_id of a Structured metadata field.

      For example:

      Ar3dProps

      The properties of the 3D viewer used to display 3D models.

      Parameter Type Description
      shadows boolean Whether to add shadow to the 3D model. Default: true
      showAR boolean Whether to show the 'View in AR' button. Default: false

      For example:

      BreakpointProps

      An object defining a single breakpoint value plus the configuration parameters (options) to override when the width of the Product Gallery widget is less than or equal to this number. Any parameter can be overridden except for the required parameters.

      Parameter Type Description
      breakpoint int (Required) All the other included in this object will only apply when the width of the Product Gallery widget is less than or equal to this number. Default: 520
      {options} The configuration parameters to override for the given breakpoint.

      For example:

      Color

      A string value representing an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color.

      For example:

      #FFAAFF

      DisplayProps

      Parameter Type Description
      mode DisplayMode The display mode for the widget. Default: "classic"
      spacing int The spacing between assets in pixels. Default: 5
      Relevant only when mode is set to 'expanded'.
      columns int The number of columns to display simultaneously. Default: 1
      Relevant only when mode is set to 'expanded'.
      topOffset int The offset of the widget from the top of the page in pixels. Default: 0
      Relevant only when mode is set to 'expanded'.
      bottomOffset int The offset of the widget from the bottom of the page in pixels. Default: 0
      Relevant only when mode is set to 'expanded'.

      For example:

      IndicatorProps

      Parameter Type Description
      color Color The color to use for the indicators. Default: ThemeProp.onPrimary
      selectedColor Color The color to use for the currently selected indicator. Default: ThemeProp.active
      shape IndicatorShape The shape of the indicators. Default: "round"
      size int The width of the indicators in pixels. Default: 8
      spacing int The space to add between the indicators in pixels. Default: 3
      sticky boolean Whether the Carousel scrolls with the main viewer or is always visible next to it. Default: true
      Relevant only when display mode is set to 'expanded'.

      For example:

      LoaderProps

      Parameter Type Description
      color Color The color of the loading spinner. Default: "#000"

      Relevant only when style is not set to 'custom'.
      opacity float The opacity of the loading spinner. Default: 0.5
      Relevant only when style is not set to 'custom'.
      style LoaderStyle The style of loader to use. Default: "cloudinary"
      url String The full path to a custom (animated) image to use as the loading spinner. As the spinner is scaled to 25% of the available width, it's recommended to use the SVG format to preserve quality at any sizes.
      Relevant only when style is set to 'custom'.

      For example:

      NavigationButtonProps

      Parameter Type Description
      shape ButtonShape The shape of the navigation button. Default: "none"
      iconColor Color The color to use for the navigation icon. Default: ThemeProp.onPrimary
      color Color The color of the navigation button. Default: ThemeProp.primary
      size int The width of the navigation button in pixels. Default: 54

      For example:

      SortProps

      Parameter Type Description
      source string The data source to use for sorting the assets in the display. The value of this property can be one of the following sources:
      - contextual: use the value of a Contextual metadata field for each asset, as given by the key passed in the id property.
      - metadata: use the value of a Structured metadata field for each asset as given by the external_id passed in the id property.
      - public_id: (default) use the public ID of the asset.
      id string Required when setting the source property as follows:
      For 'contextual' - the key of a Contextual metadata key-value pair.
      OR
      For 'metadata' - the external_id of a Structured metadata field.
      direction string The direction to alphanumerically sort the assets, either asc (default), or desc.

      Note
      Assets are also organized in groups of the same asset type (images, videos, spin sets and 3D models) when sorting by public ID. When sorting by a metadata or contextual source, the asset type is ignored and the assets are displayed in order only according to their id.

      For example:

      SpinProps

      Parameter Type Description
      animate SpinAnimation When to automatically spin the image. Default: "start"
      spinDirection SpinDirection The direction to spin the image. Default: "counter-clockwise"
      disableZoom boolean Whether to disable the zoom functionality for 360 spin sets. Default: false
      showTip ShowTip When to display a tip. Default: touch
      tipPosition TipPosition The position of the tip text. Default: "center"
      tipText string The text to display as a tip for screens without touch support. Default: "Drag to rotate"
      tipTouchText string The text to display as a tip for screens with touch support. Default: "Swipe to rotate"

      For example:

      ThemeProps

      The default colors defined for the theme. Overriding one of these values will update all properties that inherit from that particular ThemeProp.

      Parameter Type Description
      primary Color Default: "#FFFFFF"
      onPrimary Color Default: "#000000"
      active Color Default: "#0078FF"

      For example:

      ThumbnailProps

      Parameter Type Description
      width int The width of each thumbnail displayed in the carousel in pixels. Default: 64
      height int The height of each thumbnail displayed in the carousel in pixels. Default: 64
      spacing int The space to add between the individual thumbnails in pixels. Default: 2
      gutter int The space to add between the thumbnails and the navigation buttons in pixels. Default: 2
      borderColor Color The color of the thumbnail's border. Default: "#EBF0F4"
      borderWidth int The width of the thumbnail's border in pixels. Default: 1
      radius int The radius of the thumbnail's corners in pixels. Default: 0
      mediaSymbolPosition MediaSymbolPosition The position of the media symbol within the thumbnail. Default: "center"
      Relevant only when mediaSymbolShape is set to 'none'.
      mediaSymbolShape MediaSymbolShape The shape of the media symbol background. Default: "round"
      mediaSymbolColor Color The color of the media symbol background. Default: ThemeProp.primary
      mediaSymbolOpacity float The opacity of the media symbol background. Range: 0.0 to 1.0 Default: 0.3
      mediaSymbolIconShadow boolean Whether a shadow is added to the media symbol. Default: "false"
      mediaSymbolIconColor Color The color of the media symbol. Default: ThemeProp.onPrimary
      mediaSymbolSize int The size of the media symbol in pixels. Default: 40% of the thumbnail width
      navigationBorderColor Color The color of the navigation button's border. Default: "transparent"
      navigationBorderWidth int The width of the navigation button's border. Default: 0
      navigationColor Color The color of the Carousel navigation buttons. Default: ThemeProp.primary
      navigationFloat boolean Whether the navigation buttons float above the last thumbnails on either side of the carousel, or whether the buttons are adjacent to them. Default: false
      navigationIconColor Color The color of the Carousel navigation arrows. Default: ThemeProp.onPrimary
      navigationSize int The size of the Carousel navigation buttons in pixels. Default: 42
      navigationShape ButtonShape The shape of the Carousel navigation buttons. Default: "rectangle"
      selectedBorderPosition SelectedBorderPosition The position of the selected thumbnail's border. Default: "left"
      Relevant only when selectedStyle is set to 'border'.
      selectedBorderColor Color The color of the selected thumbnail's border. Default: ThemeProp.active
      selectedBorderWidth int The width of the selected thumbnail's border in pixels. Default: 2
      selectedBorderOpacity float The opacity of the selected thumbnail's border. Range: 0.0 to 1.0 Default: 1
      selectedGradientStart Color The color of the first color for the gradient fade effect. Default: ThemeProp.primary
      selectedGradientEnd Color The color of the second color for the gradient fade effect. Default: ThemeProp.primary
      selectedGradientDirection Direction The direction to fade between the start and end colors defined. Default: "vertical"
      selectedGradientOpacity float The opacity of the gradient fade. Range: 0.0 to 1.0 Default: 0.5
      selectedStyle SelectedStyles The style to apply to a selected thumbnail. Default: "all"
      sticky boolean Whether the Carousel scrolls with the main viewer or is always visible next to it. Default: true
      Relevant only when display mode is set to 'expanded'.

      For example:

      TipProps

      Parameter Type Description
      textColor Color The color of the tip's text. Default: #FFFFFF
      color Color The color of the tip element. Default: #000000
      radius number The radius of the tip's corners in pixels. Default: 5
      opacity number The opacity of the tip. Range: 0.0 to 1.0 Default: 0.5

      For example:

      VideoProps

      Parameter Type Description
      controls string Determines the controls that appear on the video:
      "all" - all native controls
      "play" - only the play/pause button
      "none" (default) - the user has no control and the video plays automatically in an endless loop with muted audio
      sound boolean Whether the video has sound. Default: false
      Relevant only when controls is not set to 'none'.
      autoplay boolean Whether the video should start playing automatically. Default: true
      Relevant only when controls is not set to 'none'.
      loop boolean Whether the video should play in an endless loop. Default: false
      Relevant only when controls is not set to 'none'.
      playerType string The video player to use for playing all the video assets in the Product Gallery:
      "cloudinary" - use the Cloudinary Video Player
      "native" (default) - the browser's HTML5 video player
      {config} {params} Any parameters available as Video Player configuration options can also be added to the videoProps parameter.
      Relevant only when playerType is set to 'cloudinary'.

      For example:

      ZoomProps

      Parameter Type Description
      type ZoomType The type of zoom to use. Default: "inline"
      level float The zoom factor to apply when zooming in to the image. Default: 2 (200%)
      steps int The number of zoom steps available, i.e., the number of times the user can zoom into the image. Range: 0 to 5 Default: 0
      Relevant only when type is set to 'popup'.
      stepLimit boolean Whether to limit the number of steps to not zoom in beyond the original image size. Default: false
      trigger ZoomTrigger Determines how zooming is triggered. Default: "click"
      viewerPosition ZoomViewerPosition The position of the viewer adjacent to the main viewer. Default: "right"
      Relevant only when type is set to 'flyout'.
      viewerRadius int The radius of the viewer's corners in pixels. Default: 0
      Relevant only when type is set to 'flyout'.
      viewerZIndex int The stack order of the zoom viewer element. An element with greater stack order is rendered in front of an element with a lower stack order. Default: 100
      Relevant only when type is set to 'flyout'.
      container string selector The identification of a container element on the page for displaying the zoom viewer.
      Example: "#my-zoom-container"
      Relevant only when type is set to 'flyout'.
      viewerOffset int The offset of the viewer for the zoomed-in image from main viewer. Default: 10
      Relevant only when type is set to 'flyout'. Note that this parameter is ignored when using multi-column expanded display mode.
      showLens boolean Whether to display a lens outlining the current zoomed-in portion of the image. Default: true
      Relevant only when type is set to 'flyout'.
      lensBorderColor Color The color of the lens border. Default: "#FFFFFF"

      Relevant only when showLens is set to 'true'.
      lensBorderWidth int The width of the lens border in pixels. Default: 0
      Relevant only when showLens is set to 'true'.
      lensColor Color The color of the lens. Default: "#FFFFFF"

      Relevant only when showLens is set to 'true'.
      lensOpacity float The opacity of the lens. Range: 0.0 to 1.0 Default: 0.5
      Relevant only when showLens is set to 'true'.
      lensRadius int The radius of the lens' corners in pixels. Default: 0
      Relevant only when showLens is set to 'trueˇ'.
      lensShadow boolean Whether a shadow is added to the lens. Default: "true"
      Relevant only when showLens is set to 'true'.
      showTip ShowTip When to display a tip. Default: touch
      tipText string The text to display as a tip for screens without touch support. Default: "Click to zoom"
      tipTouchText string The text to display as a tip for screens with touch support. Default: "Tap to zoom"
      tipPosition TipPosition The position of the tip text. Default: "bottom"

      For example:

      ZoomPopupProps

      Parameter Type Description
      backdropColor Color The color of the backdrop. Default: "#000000"
      backdropOpacity float The opacity of the backdrop. Range: 0.0 to 1.0 Default: 1.0
      zIndex int The stack order of the popup element on the page. Default: 100

      For example:

      ENUMs

      • AspectRatio
      • ButtonShape
      • CarouselLocation
      • CarouselStyle
      • Direction
      • DisplayMode
      • IndicatorShape
      • LoaderStyle
      • MediaSymbolPosition
      • MediaSymbolShape
      • Navigation
      • NavigationPosition
      • SelectedBorderPosition
      • SelectedStyles
      • Transitions
      • ZoomButtonPosition
      • ZoomTrigger
      • ZoomType
      • ZoomViewerPosition

      AspectRatio

      A string value setting the aspect ratio of the main viewer:

      Value Notes
      square
      1:1
      3:4
      4:3
      4:6
      6:4
      5:7
      7:5
      5:8
      8:5
      9:16
      16:9

      ButtonShape

      A string value setting the shape of the button:

      Value Notes
      none The button is transparent and only an enlarged icon appears.
      round
      square
      radius
      rectangle

      CarouselLocation

      A string value setting the location of the carousel relative to the widget:

      Value Notes
      right -
      left -
      top Not supported in 'expanded' display mode.
      bottom Not supported in 'expanded' display mode.

      CarouselStyle

      A string value setting the display style of the carousel:

      Value Notes
      none No carousel component is displayed: only the main viewer navigation buttons are available for cycling through the assets.
      thumbnails thumbnails
      indicators indicators

      Direction

      A string value setting the colorization priorities of a gradient fade effect:

      Value Notes
      vertical Use the 'start' color at the top fading into the 'end' color at the bottom.
      horizontal Use the 'start' color on the left fading into the 'end' color on the right.

      DisplayMode

      A string value setting the display mode for the widget:

      Value Notes
      classic The assets are displayed one at a time in the main viewer.
      expanded The main viewer is expanded and all assets are displayed in vertical columns (1 by default). Not supported by mobile devices where the widget always uses classic mode.

      IndicatorShape

      A string value setting the shape of the carousel indicators:

      Value Notes
      round
      square
      radius

      LoaderStyle

      A string value setting the type of loading spinner to use while assets are loading. The spinner is scaled to 25% of the available width:

      Value Notes
      cloudinary
      circle
      custom A custom loading spinner as specified by the url parameter.

      MediaSymbolPosition

      A string value setting the position of the icon:

      Value Notes
      top-left -
      top-right -
      bottom-left -
      bottom-right -
      center -

      MediaSymbolShape

      A string value setting the shape of the media icon background:

      Value Notes
      none
      round
      square
      radius

      Navigation

      A string value setting when to display navigation buttons:

      Value Notes
      none The buttons never appear.
      always The buttons always appear.
      mouseover The buttons only appear when the mouse pointer is over the main viewer (for desktops only - buttons will always appear on mobile devices).

      NavigationPosition

      A string value setting the position of the navigation buttons:

      Value Notes
      inside Aligns the edge of the navigation arrow to the inside edge of the widget.
      middle Aligns the middle of the navigation arrow to the inside edge of the widget.
      offset Offsets the edge of the navigation arrow from the inside edge of the widget, according to the value of the navigationOffset parameter.

      SelectedBorderPosition

      A string value setting which borders are displayed on a selected thumbnail:

      Value Notes
      top
      bottom
      left
      right
      top-bottom
      left-right
      all

      SelectedStyles

      A string value setting the effect for the selected thumbnail in the carousel:

      Value Notes
      border
      gradient
      all

      ShowTip

      A string value setting when to show the tip:

      Value Notes
      touch Only on touch enabled devices
      desktop Only on desktops
      all On touch enabled devices and desktops
      never No tips shown

      Sort

      A string value setting how to apply an alphanumeric sort:

      Value Notes
      none The assets are displayed in the same order as they are given in the mediaAssets parameter.
      asc In ascending order by PublicID.
      desc In descending order by PublicID.

      SpinAnimation

      A string value setting when to automatically spin the image:

      Value Notes
      none
      start As soon as the 360 spin set appears in the main viewer.
      end When the user finishes manually rotating the 360 spin set.
      both

      SpinDirection

      A string value setting the direction to spin the image:

      Value Notes
      clockwise
      counter-clockwise

      TipPosition

      A string value setting the position of the tip:

      Value Notes
      top -
      center -
      bottom -

      Transitions

      A string value representing the effect to apply when transitioning between media assets:

      Value Notes
      none -
      slide -
      fade -

      ZoomTrigger

      A string value setting the zoom operation:

      Value Notes
      click Zoom is activated when clicking anywhere over the asset.
      hover Zoom is activated when hovering over the asset (applies to desktops only).

      ZoomType

      A string value setting the type of zoom:

      Value Notes
      inline The zoomed in image appears within the same area as the main viewer.
      flyout The zoomed in image appears adjacent to the main viewer. Not supported by mobile devices where the widget will use 'inline' instead.
      popup The zoomed in image appears in a pop-up box.

      ZoomViewerPosition

      A string value setting the position of the zoom viewer relative to the main viewer:

      Value Notes
      top -
      right -
      left -
      bottom -

      Instance methods

      The following methods can be used with the Product Gallery instance returned by the galleryWidget method:

      • Render
      • Destroy
      • On
      • Update

      Render

      Use the render method to render an initialized Product Gallery widget object.

      For example:

      Destroy

      Use the destroy method to erase the Product Gallery widget and remove it from memory.

      For example:

      On

      Use the on method to register to a specific event.

      For example:

      Update

      The update method accepts a map of configuration parameters to update an already rendered widget.

      For example:

      Events

      The following events can be registered with the on method of a Product Gallery instance.

      Event Description
      indicatorclick An indicator icon has been clicked.
      mouseenter The mouse cursor is over the widget.
      mouseleave The mouse cursor has left the widget.
      spinclick A 360 spin set has been clicked.
      thumbclick A thumbnail has been clicked.
      thumbnext The 'Next' thumbnail navigation button has been clicked.
      thumbprev The 'Previous' thumbnail navigation button has been clicked.
      videopause A video has been paused.
      videoprogress A video has progressed (triggered at 25%, 50%, 75% and 100%).
      videostart A video has started playing.
      viewernext The 'Next' main viewer navigation button has been clicked.
      viewerprev The 'Previous' main viewer navigation button has been clicked.
      zoomin The image has been zoomed in.
      zoomout The image has been zoomed out.

      The following information is included when the event is triggered, and is available in the (data) structure:

      • label: The PublicID of the current media asset displayed.
      • timestamp: The time the event occurred.
      • progress: The amount that the video has progressed - only relevant for the videoprogress event.

      For example:

      See also
      For more information on the Cloudinary Product Gallery, see the Product Gallery guide.

      ✔️ Feedback sent!

      ✖️  
      How helpful was this doc page?

      Thanks for submitting your rating. We got it!
      We'd love to hear more. Tell us what you liked and how we can make this page even better:

      *


      Cloudinary is committed to protecting your information security. For details, see our privacy policy.

      For additional assistance, open a support request.

      Error

      Unfortunately there's been an error sending your feedback.

      Rate this page:

      • Upload Widget API reference
      • Media Editor API reference
      Cloudinary Logo - White
      Products
      • Programmable Media
      • DAM
      • Demos
      • Pricing
      • Roadmap
      • FAQ
      Solutions
        • Why Cloudinary
        • Video API
        • E-commerce
        • Retail
        • Media & Entertainment
        • Travel & Hospitality
        • Non-Profits
        • Our Customers
        • Resource Library
        Developers
        • Getting Started
        • Documentation
        • Community
        • SDKs
        • Add-ons
        • Podcasts
        • Cookbook
        Company
        • About Us
        • Customers
        • Partners
        • Events
        • Careers
        • Newsroom
        • Blog
        • Brand Assets
        • Trust
        Contact Us
        • Technical Support
        • Contact Sales
        • Education & Training
        • Institute of Quality & Control
        • GDPR
        • SOC
        • Forbes Best Startup Employers 2020
        • MarTech Breakthrough Awards
        • Best Places to Work SVBJ 2018
        • 2020 The World's Best Cloud Companies
        • Terms of Use
        • Privacy Policy
        • DMCA Notice

        © 2024 Cloudinary. All rights reserved.