Product Gallery API reference

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

Code explorer: Product Gallery widget example

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

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

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

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:

Widget parameters

Main viewer parameters

Carousel parameters

Navigation parameters

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.

For example:

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

AccessibilityProps

The accessibility properties to override for the widget.

For example:

{
  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.

For example:

{   // 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:

#FFAAFF

DisplayProps

For example:

{
  mode: 'expanded',
  spacing: 10,
  columns: 2
}

IndicatorProps

For example:

{
  size: 10,
  spacing: 4
}

LoaderProps

For example:

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

NavigationButtonProps

For example:

{
  shape: 'square',
  size: 60
}

SortProps

For example:

{ 
  source: 'metadata', 
  id: 'sort_id',
  direction: 'desc' 
}

SpinProps

For example:

{
  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.

For example:

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

ThumbnailProps

For example:

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

TipProps

For example:

{
  radius: 10,
  opacity: 0.3
}

VideoProps

For example:

{
  controls: 'all',
  autoplay: false
}

ZoomProps

For example:

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

ZoomPopupProps

For example:

{
  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:

ButtonShape

A string value setting the shape of the button:

CarouselLocation

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

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
indicators

Direction

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

DisplayMode

A string value setting the display mode for the widget:

IndicatorShape

A string value setting the shape of the carousel indicators:

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:

MediaSymbolShape

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

Navigation

A string value setting when to display navigation buttons:

NavigationPosition

A string value setting the position of the navigation buttons:

SelectedBorderPosition

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

SelectedStyles

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

ShowTip

A string value setting when to show the tip:

Sort

A string value setting how to apply an alphanumeric sort:

SpinAnimation

A string value setting when to automatically spin the image:

SpinDirection

A string value setting the direction to spin the image:

TipPosition

A string value setting the position of the tip:

Transitions

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

ZoomTrigger

A string value setting the zoom operation:

ZoomType

A string value setting the type of zoom:

ZoomViewerPosition

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

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:

myGallery.render();

Destroy

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

For example:

myGallery.destroy();

On

Use the on method to register to a specific event.

For example:

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:

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

Events

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

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:

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