Image Gallery

This component can be used to display an image gallery on the product page. It features a carousel view, with a fullscreen button to display the full-resolution product image. Swipe gestures to navigate between images are supported on mobile devices.

Props

Copy

Copied

  images: ProductImage[];
  /** @default 3:4
   * The aspect ratio used for the gallery images. If unknown, pass `null` */
  aspect?: string;
  /**
   * @default [1, 1, 1 / 2, 1 / 2]
   * An array of sizes to be used for the img
   * srcSet. Each size maps to a breakpoint *
   * See the `Image` docs for a more detailed explanation
   */
  sizes?: number[];
    /**
   * @default [1, 1, 1, 1 ]
   * As above, but used for the fullscreen image
   */
  fullScreenSizes?: number[];
  /**
   * @default ['5rem']
   */
  thumbnailSizes?: number[];
  /** @default bottom
   * The position of image thumbnails */
  thumbnailPosition?: 'top' | 'right' | 'bottom' | 'left';
  /** Optional background colour for the gallery */
  backgroundColor?: string;
  /** A ref to forward on to the image gallery in order to access imperative functions */
  galleryRef?: {
    current: any;
  };
  /** The quality of the gallery images - a number between 0 and 100 **/
  quality?: number;
  /** The quality of the thumbnail images - a number between 0 and 100 **/
  thumbnailQuality?: number;

Usage

Copy

Copied

<Playground>
  {() => {
    const images = [
      {
        alt: "Sample image",
        title: "Sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/a/a8/Sydney_harbour_bridge_new_south_wales.jpg/1600px-Sydney_harbour_bridge_new_south_wales.jpg",
          },
        ],
      },
      {
        alt: "Another sample image",
        title: "Another sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/7/7c/Sydney_Opera_House_-_Dec_2008.jpg/1600px-Sydney_Opera_House_-_Dec_2008.jpg",
          },
        ],
      },
      {
        alt: "Bondi",
        title: "Bondi sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/e/e5/Bondi_Beach_Sydney_Australia_7.jpg/2560px-Bondi_Beach_Sydney_Australia_7.jpg",
          },
        ],
      },
    ];
    return <Gallery images={images} aspect="4:3" />;
  }}
</Playground>

Thumbnails on the side:

Copy

Copied

<Playground>
  {() => {
    const images = [
      {
        alt: "Sample image",
        title: "Sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/a/a8/Sydney_harbour_bridge_new_south_wales.jpg/1600px-Sydney_harbour_bridge_new_south_wales.jpg",
          },
        ],
      },
      {
        alt: "Another sample image",
        title: "Another sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/7/7c/Sydney_Opera_House_-_Dec_2008.jpg/1600px-Sydney_Opera_House_-_Dec_2008.jpg",
          },
        ],
      },
      {
        alt: "Bondi",
        title: "Bondi sample image",
        sizes: [
          {
            url: "https://res.cloudinary.com/demo/image/fetch/h_1000,c_scale/https://upload.wikimedia.org/wikipedia/commons/thumb/e/e5/Bondi_Beach_Sydney_Australia_7.jpg/2560px-Bondi_Beach_Sydney_Australia_7.jpg",
          },
        ],
      },
    ];
    return <Gallery images={images} thumbnailPosition="left" aspect="4:3" />;
  }}
</Playground>

If the aspect ratio of the gallery images is not consistent

If you don't have a standard aspect ratio for all images in the store, you can set the aspect to {null}. This will place the image inside a 1:1 container, and the original aspect ratio will be retained.

useSwitchToVariantOptions

Product variants may have images associated with them. These will appear in the gallery alongside the "base" product images. You can use this hook to automatically switch the focused gallery image to the appropriate image when the user selects a variant.

Import

import { useSwitchToVariantImage } from '@jetshop/core/hooks/Product';

Usage

Copy

Copied

function ImageGallery({images}) {

  // First create a ref. This needs to be passed in to the Gallery, and will be
  // attached to the Gallery component.
  const galleryRef = React.createRef();

  // Enable switching gallery to image of selected variant
  useSwitchToVariantImage({
    galleryImages: images,
    galleryRef
  });

  // Make sure to pass the galleryRef in to the Gallery
  return <Gallery aspect={'1:1'} images={images} galleryRef={galleryRef}>

}

This works by attaching a ref to the Gallery component, which allows us to access the imperative functions that the component exposes. The hook takes care of the rest!

Now that you have galleryRef, you can also use any of the imperative functions mentioned in the docs for the react-image-gallery component. So, for example, you could create your own fullscreen button like this:

Copy

Copied

<button onClick={() => galleryRef.current.fullScreen()}>Go fullscreen</button>