Cloudinary Logo Docs Documentation
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
      • Transformations and optimizations
      • Digital Asset Management (DAM)
      • Administration
      • Platform integrations
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • 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
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
      • Responsive images
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
    • 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 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
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
      • DAM administrator guide
    • Media Optimizer
      • Overview
      • Quick starts
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
      • Salesforce Commerce Cloud Cartridges
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
      • WordPress Plugin
      • Zapier Integration
      • Partner-built integrations
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
      • AR/3D Viewer and 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • Ruby/Rails SDK
      • PHP SDK
      • Python SDK
      • Node.js SDK
      • Java SDK
      • .NET SDK
      • Go SDK
      • Dart SDK
      • PHP SDK (Legacy)
    • Frontend SDKs
      • JavaScript SDK
      • Angular SDK
      • React SDK
      • Vue.js SDK
      • jQuery SDK
      • JavaScript SDK (Legacy)
      • Angular SDK (Legacy)
      • React SDK (Legacy)
      • Vue.js SDK (Legacy)
    • Mobile SDKs
      • iOS SDK
      • Android SDK
      • Flutter SDK
      • Kotlin SDK
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
BlogTrainingSupportPricingCommunityMediaJamsPodcastsDemosRoadmapCookbookAdditional Resources
  • Blog
  • Training
  • Support
  • Pricing
  • Community
  • MediaJams
  • Podcasts
  • Demos
  • Roadmap
  • Cookbook
  • Additional Resources
Login
sign up for free
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
        • Upload programmatically
        • Create upload presets
        • Auto-tag assets
        • Diagnosing error codes
        • Upload assets in a React app
        • Deliver images with the Next.js Image component
        • Generate upload signature
        • Postman collections introduction
        • Find your credentials
        • Configure the Node.js SDK
        • Get started with the CLI
        • Scripting with the CLI
        • Get creative with the CLI
        • Upload with the CLI
        • Upload Widget
        • Product Gallery
        • Product Gallery accessibility
      • Transformations and optimizations
        • Transformation basics
        • Optimization tips
        • Gravity-based crops for images
        • Convert videos to animated images
        • Text overlay transformations
        • Complex transformations
        • Named transformations
        • Advanced image components
        • Zoompan effect
        • Social media image cards in Next.js
      • Digital Asset Management (DAM)
        • Folder sharing
        • Collection management
        • Collection sharing
        • Transformation presets
        • Media Library upload
        • Video management intro
        • Advanced Search
      • Administration
        • Enable automatic backups
        • Restore asset versions
        • Restore deleted assets
      • Platform integrations
        • Adobe CC Connector overview
        • SAP Commerce Extension overview
        • SFCC site cartridge intro
        • SFCC site cartridge installation
        • SFCC site cartridge modes
        • SFCC site cartridge videos
        • SFCC Page Designer cartridge
        • SFMC app - image block
        • SFMC app - video to GIF block
        • Shopify app
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • 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
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
        • Live streaming WebRTC (Beta)
        • Live streaming RTMP
        • Simulated live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
        • Optimize images
        • Optimize videos
        • Optimize audio files
      • 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
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
        • Video Player features
        • Installation and setup
        • How to embed the Video Player
        • Video Player customization
        • Playlists and recommendations
        • HLS and MPEG-DASH
        • Events and analytics
        • Video ads and monetization
        • Shoppable Video
        • Interactive Video (Beta)
        • Video Player API reference
    • 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 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
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
        • Uploading and storing assets
        • Folders and collections
        • Media asset search
          • Global Search
          • Advanced Search
          • Query Builder
          • Visual Search (Beta)
        • Managing individual media assets
      • DAM administrator guide
        • User and group management
          • SAML provisioning
        • Settings and preferences
          • Dynamic folders
        • Upload presets
        • Structured metadata
        • Asset management
        • Usage data
        • Dynamic templating
    • Media Optimizer
      • Overview
      • Quick starts
        • Walkthrough
        • Deliver from a web address
        • Deliver from an AWS S3 bucket
        • Deliver from a Google Storage bucket
        • Deliver using an HTTP proxy
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
        • Magento product catalog API
      • Salesforce Commerce Cloud Cartridges
        • Page Designer Cartridge
          • Custom integration
        • Site Cartridge
          • Operational overview
          • Site Cartridge for SiteGenesis
          • Site Cartridge for SFRA
          • Site Cartridge FAQ
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
        • User guide
      • WordPress Plugin
        • Developer guide
      • Zapier Integration
      • Partner-built integrations
        • Agility Custom Field
        • Actindo Connection
        • Builder.io App Extension
        • Chioro Operation
        • Comestri Channel
        • Conscia Connector
        • Contentful App
        • Contentstack Custom Field Extension
        • Creative Force Asset Delivery
        • GraphCMS UI Extension
        • Kontent.ai Custom Element
        • Magnolia DAM Connector
        • Movidmo Upload Connector
        • OpenText TeamSite Connector
        • Sanity Plugin
        • Sitefinity DAM System Integration
        • Smint.io Data Source Connector
        • Stackbit Integration
        • Storyblok App Integration
        • Syndigo Advanced DAM App
        • Uniform Integration
        • Vue Storefront Component
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
        • Oveview
        • Getting started
        • Build your first flow
        • Block reference
      • AR/3D Viewer and 3D Model Configurator
        • Oveview
        • Customizations
        • 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • 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 administration
        • CarrierWave integration
        • Attachinary integration
        • Active Storage integration
      • PHP SDK
        • PHP introduction
        • PHP quick start
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP SDK reference
      • Python SDK
        • Python introduction
        • Python quick start
        • Python image and video upload
        • Python image transformations
        • Python video transformations
        • Python asset administration
      • 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 administration
      • Java SDK
        • Java introduction
        • Java quick start
        • Java image and video upload
        • Java image transformations
        • Java video transformations
        • Java asset administration
      • .NET SDK
        • .NET introduction
        • .NET quick start
        • .NET image and video upload
        • .NET image transformations
        • .NET video transformations
        • .NET asset administration
      • Go SDK
        • Go introduction
        • Go quick start
        • Go image and video upload
        • Go media transformations
        • Go asset administration
        • Go SDK Reference
      • Dart SDK
        • Dart introduction
        • Dart quick start
        • Dart image and video upload
        • Dart media transformations
      • PHP SDK (Legacy)
        • PHP introduction
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP migration guide
    • Frontend SDKs
      • JavaScript SDK
        • JavaScript introduction
        • JavaScript quick start
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript SDK reference
        • Transformation Builder reference
      • Angular SDK
        • Angular introduction
        • Angular quick start
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular SDK reference
        • Transformation Builder reference
      • React SDK
        • React introduction
        • React quick start
        • React image and video upload
        • React image transformations
        • React video transformations
        • 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
        • Transformation Builder reference
      • jQuery SDK
        • jQuery introduction
        • jQuery image and video upload
        • jQuery image transformations
        • jQuery video transformations
      • JavaScript SDK (Legacy)
        • JavaScript introduction
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript migration guide
      • Angular SDK (Legacy)
        • Angular introduction
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular migration guide
      • 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
    • Mobile SDKs
      • iOS SDK
        • iOS introduction
        • iOS image and video upload
        • iOS image transformations
        • iOS video transformations
      • Android SDK
        • Android introduction
        • Android image and video upload
        • Android image transformations
        • Android video transformations
      • Flutter SDK
        • Flutter introduction
        • Flutter quick start
        • Flutter image and video upload
        • Flutter media transformations
      • Kotlin SDK
        • Kotlin media transformations
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
Login
sign up for free
  • References
  • Product Gallery API

Product Gallery API reference

Last updated: Jan-01-2023

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

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:

Copy to clipboard
const myGallery = cloudinary.galleryWidget({ 
  container: "#my-gallery", 
  cloudName: "demo", 
  mediaAssets: [{ tag: "bag" }]    // by default mediaType: "image"
});

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.
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 dont want to preload any assets ([]).
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
  • 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.
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.
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'.

For example:

Copy to clipboard
{
  tag: 'bag',
  mediaType: 'video',
  transformation: { 
    crop: "fill", 
    transformation: [{ overlay: "cloudinary_icon_blue", gravity: "south_east" }]}
}

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:

Copy to clipboard
{
  mediaAltSource: 'metadata', 
  mediaAltId: 'alt_id'
}

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:

Copy to clipboard
{   // this is the current default breakpoint
  breakpoint: 520,
  navigation: 'always',
  carouselLocation: 'bottom',
  thumbnailProps: {
   selectedBorderPosition: 'bottom' }
}

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:

Copy to clipboard
#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:

Copy to clipboard
{
  mode: 'expanded',
  spacing: 10,
  columns: 2
}

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:

Copy to clipboard
{
  size: 10,
  spacing: 4
}

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:

Copy to clipboard
{
  style: 'custom',
  url: 'https://www.example.come/my_loading_spinner.svg'
}

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:

Copy to clipboard
{
  shape: 'square',
  size: 60
}

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:

Copy to clipboard
{ 
  source: 'metadata', 
  id: 'sort_id',
  direction: 'desc' 
}

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:

Copy to clipboard
{
  animate: 'end',
  animateDuration: 3000
}

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:

Copy to clipboard
{
  primary: '#FFF',
  onPrimary: 'yellow',
  active: '#000000'
}

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:

Copy to clipboard
{
  width: 100,
  height: 100,
  borderColor: 'red',
  selectedBorderWidth: 5
}

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:

Copy to clipboard
{
  radius: 10,
  opacity: 0.3
}

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:

Copy to clipboard
{
  controls: 'all',
  autoplay: false
}

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:

Copy to clipboard
{
  type: 'flyout',
  level: 3,
  viewerPosition: 'top',
  lensOpacity: 0.3
}

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:

Copy to clipboard
{
  backdropColor: "#d75900",
  backdropOpacity: 0.5
}

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:

Copy to clipboard
myGallery.render();

Destroy

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

For example:

Copy to clipboard
myGallery.destroy();

On

Use the on method to register to a specific event.

For example:

Copy to clipboard
myGallery.on('mouseenter', (data) => {
  console.log('MouseEnter', data);
});

Update

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

For example:

Copy to clipboard
myGallery.update({
  mediaAssets: [{ tag: "sack" }],
  aspectRatio: "3:4"
});

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:

Copy to clipboard
myGallery.on('thumbclick', (data) => {
  console.log('ThumbClick', data);
});

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:

  • Video Player 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
    • 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

    © 2023 Cloudinary. All rights reserved.