Image & Video APIs
Menu

Product Gallery API reference

Last updated: May-12-2025

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

The options in this reference relate to the latest version of the Cloudinary Product Gallery.

Tips

Code explorer: Product Gallery widget example

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

This code is also available in GitHub.

Tip
For versions of this code explorer in other frameworks, see:

Tip
Enjoy interactive learning? Check out more code explorers!

On this page:

Parameters

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

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's populated with all images that have the "bag" tag:

Required parameters

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

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

Widget parameters

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

Main viewer parameters

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

Carousel parameters

Parameter Type Description
carouselLocation CarouselLocation The location of the carousel relative to the main viewer. Default: "left"
carouselOffset int The space between the main viewer and the carousel in pixels. Default: 5
carouselStyle CarouselStyle The display style of the carousel. Default: "thumbnails"
carouselLoop string The behavior to use when the user clicks either the next button while the last asset in the carousel is currently displayed, or the previous button with the first asset in the carousel displayed. Set to jump to keep the buttons enabled, allowing the user to jump back to the first item or forward to the last item, instead of displaying disabled previous or next buttons (the default).
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

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's 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 are 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.
fetchPriority string Tells the browser the priority to fetch assets, either "low", "high", or "auto" (default). Note that fetchPriority = "high" is always set on the first asset in a gallery. (See the MDN docs for details).
transformation Object The Cloudinary transformation to apply. Any set of transformation options can be applied in addition to the default transformation parameters, or to override their values.

To apply this transformation before the default transformation parameters, set prefixed: false in this object.
thumbnailTransformation Object The Cloudinary transformation to apply to the thumbnail image(s) used in the carousel to represent the media asset. This value overrides the transformation parameter (only for thumbnails) if that's also given.

To apply this transformation before the default transformation parameters, set prefixed: false in this object.
altText string The string to use as the Alt accessibility text in the gallery.
videoPlayerSource Object The Cloudinary Video Player source options to apply to the video.
Relevant only when the playerType property of the videoProps parameter is set to 'cloudinary'.

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

For example:

AccessibilityProps

The accessibility properties to override for the widget.

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

For example:

Ar3dProps

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

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

For example:

BreakpointProps

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

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

For example:

Color

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

For example:

#FFAAFF

DisplayProps

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

For example:

IndicatorProps

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

For example:

LoaderProps

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

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

For example:

NavigationButtonProps

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

For example:

SortProps

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

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

For example:

SpinProps

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

For example:

ThemeProps

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

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

For example:

ThumbnailProps

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

For example:

TipProps

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

For example:

VideoProps

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

For example:

ZoomProps

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

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

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

For example:

ZoomPopupProps

Parameter Type Description
backdropColor Color The color of the backdrop. Default: "#000000"
backdropOpacity float The opacity of the backdrop. Range: 0.0 to 1.0 Default: 1.0
initialZoom boolean Whether to open the zoom popup already zoomed in. Default: false
zIndex int The stack order of the popup element on the page. Default: 100

For example:

ENUMs

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're 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

Renders an initialized Product Gallery widget object.

For example:

Destroy

Erases the Product Gallery widget and removes it from memory.

For example:

On

Registers to a specific event.

For example:

Update

Accepts a map of configuration parameters to update an already rendered widget.

For example:

setItem

Selects the asset to display by passing its index number. Note that the first asset has an index of 0.

For example:

nextItem

Displays the next asset.

For example:

prevItem

Displays the previous asset.

For example:

getActiveItem

Returns the currently displayed asset.

For example:

getActiveIndex

Returns the index of the currently displayed asset.

For example:

Events

You can register to the following events 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!

Rate this page: