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
    • 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
      • Audio transformations
      • Video generation
      • Advanced video transformations
    • Optimization
      • Overview
      • Image optimization
      • Responsive images
      • Video optimization
      • Adaptive bitrate streaming
      • Audio optimization
    • Delivery
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and Players
      • Upload Widget
      • Product Gallery
      • Media Library Widget
      • Media Editor
      • Video Player
    • Native mobile development
    • 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 (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
    • SDK references
      • Transformation Builder reference
      • React SDK reference
      • Vue.js SDK reference
      • JavaScript SDK reference
      • Angular SDK reference
      • PHP SDK reference
      • Go SDK Reference
    • Postman collections
    • Upload Widget API
    • Product Gallery API
    • Media Editor API
    • Video Player API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • 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
      • Kotlin SDK
      • Flutter SDK
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
Blog Training Support Pricing Community MediaJams Podcasts Demos Roadmap Cookbook Additional 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
        • Latest: Feb 21, 2023
        • Archives
          • Dec 27, 2022
    • Digital Asset Management
      • DAM get started guide
      • Release notes
        • Latest: March 22, 2023
        • Archives
          • Feb 22, 2023
          • Nov 21, 2022
    • Video tutorial library
      • Programmatic asset management
        • Programmatic upload and delivery
          • Upload programmatically
          • Create upload presets
          • Auto-tag assets
          • Diagnosing error codes
          • Upload assets in a React app
          • Upload assets in a SvelteKit app
          • Deliver images with the Next.js Image component
        • Interaction with Cloudinary APIs
          • Generate upload signature
          • Postman collections introduction
        • Cloudinary SDKs
          • Find your credentials
          • Configure the Node.js SDK
          • Configure the Vue.js SDK
        • 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 accessibility
          • Video Player in React
      • Transformations and optimizations
        • Get started with transformations
          • Transformation basics
          • Optimization tips
          • Gravity-based crops for images
          • Content-aware video cropping
          • Convert videos to animated images
        • Advanced transformation features
          • Text overlay transformations
          • Complex transformations
          • Named transformations
          • Advanced image components
          • Zoompan effect
          • Video transformations
        • Transformations for social media
          • Social media image cards in Next.js
      • Digital Asset Management (DAM)
        • DAM administration
          • Folder sharing
          • Collection management
          • Collection sharing
          • Transformation presets
        • Using DAM features
          • 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
        • Salesforce Commerce Cloud cartridges
          • SFCC B2C Commerce cartridge intro
          • SFCC B2C Commerce cartridge installation
          • SFCC B2C Commerce cartridge modes
          • SFCC B2C Commerce cartridge videos
          • SFCC Page Designer cartridge
        • Salesforce Marketing Cloud app
          • SFMC app - image block
          • SFMC app - video to GIF block
        • Shopify app
        • Netlify plugin
  • Guides
    • 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
      • Audio transformations
      • Video generation
      • Advanced video transformations
        • Converting videos to animated images
        • Conditional transformations
        • User-defined variables and arithmetic transformations
        • Live streaming
          • Live streaming WebRTC (Beta)
          • Live streaming RTMP
          • Simulated live streaming
    • Optimization
      • Overview
      • Image optimization
      • Responsive images
        • Using HTML and dynamic image transformations
        • Using JavaScript frontend frameworks
        • Using the cloudinary-core JS library
        • Using client hints
      • Video optimization
      • Adaptive bitrate streaming
      • Audio optimization
    • Delivery
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and Players
      • Upload Widget
      • Product Gallery
      • Media Library Widget
      • Media Editor
      • 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
    • Native mobile development
    • 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 SSO
        • 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
        • B2C Commerce Cartridge
          • Operational overview
          • B2C Commerce Cartridge for SFRA
          • B2C Commerce Cartridge for SiteGenesis
          • B2C Commerce Cartridge FAQ
        • Page Designer Cartridge
          • Custom integration
      • 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 (Beta)
        • Overview
        • Getting started
        • User Guide
        • 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
    • SDK references
      • Transformation Builder reference
      • React SDK reference
      • Vue.js SDK reference
      • JavaScript SDK reference
      • Angular SDK reference
      • PHP SDK reference
      • Go SDK Reference
    • Postman collections
    • Upload Widget API
    • Product Gallery API
    • Media Editor API
    • Video Player API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • 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 administration
      • Python SDK
        • Python introduction
        • Python quick start
        • Python image and video upload
        • Python image transformations
        • Python video transformations
        • Python asset administration
      • PHP SDK
        • PHP introduction
        • PHP quick start
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP SDK reference
      • Java SDK
        • Java introduction
        • Java quick start
        • Java image and video upload
        • Java image transformations
        • Java video transformations
        • Java asset administration
      • 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
      • .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
      • 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
        • 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 SDK reference
        • Transformation Builder reference
      • JavaScript SDK
        • JavaScript introduction
        • JavaScript quick start
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • 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 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
      • Kotlin SDK
        • Kotlin media transformations
      • Flutter SDK
        • Flutter introduction
        • Flutter quick start
        • Flutter image and video upload
        • Flutter 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:

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: 0Relevant 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:

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).ORFor 'metadata' - the external_id of a Structured metadata field.

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:

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: 1Relevant only when mode is set to 'expanded'.
topOffset int The offset of the widget from the top of the page in pixels. Default: 0Relevant only when mode is set to 'expanded'.
bottomOffset int The offset of the widget from the bottom of the page in pixels. Default: 0Relevant 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: trueRelevant 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.5Relevant 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.ORFor '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: trueRelevant 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: falseRelevant only when controls is not set to 'none'.
autoplay boolean Whether the video should start playing automatically. Default: trueRelevant only when controls is not set to 'none'.
loop boolean Whether the video should play in an endless loop. Default: falseRelevant 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: 0Relevant 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: 0Relevant 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: trueRelevant 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: 0Relevant 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.5Relevant 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

    © 2023 Cloudinary. All rights reserved.