🎉 We are thrilled to introduce FastStore v2. If you are looking for documentation of the previous version of FastStore, please refer to FastStore v1.

Image Gallery

An ImageGallery is used when you want to display a series of photos in a gallery on a post or page.

According to the quantity of Image to be displayed, the ImageGallerySelector will be displayed.


Import

Import the component from @faststore/ui

import {
  ImageGallery,
  ImageGallerySelector,
  ImageGalleryViewer,
} from '@faststore/ui'

Import Styles

import '@faststore/ui/src/components/organisms/ImageGallery/styles.scss'

Usage

⚠️

Add the data-fs-image attribute in all <img> tags to ensure they work as expected. You can find an example in the Code tab below for reference.


Props

Image Gallery

NameTypeDescriptionDefault
testIdstringID to find this component in testing tools (e.g.: cypress, testing-library, and jest).fs-image-gallery
images*ImageElementData[]List of images that should be rendered.
ImageComponent*ImageComponentTypeFunction that returns a React component that will be used to render images.
selectedImageIdx*numberThe currently active thumbnail.
setSelectedImageIdx*(idx: number) => voidEvent handler for clicks on each thumbnail.
imagePosition"top" | "center" | "bottom"The position of the thumbnail and gallery image.center

Image Gallery Selector

NameTypeDescriptionDefault
testIdstringID to find this component in testing tools (e.g.: cypress, testing-library, and jest).fs-image-gallery-selector
currentImageIdx*numberThe currently active thumbnail.
aria-labelstringFor accessibility purposes, define a string that labels the current element.
navigationButtonLeftAriaLabelstringFor accessibility purposes, define a string that labels the left navigation icon button.Backward slide image selector
navigationButtonRightAriaLabelstringFor accessibility purposes, define a string that labels the right navigation button icon.Forward slide image selector
onSelect*(imageIdx: number) => voidEvent handler for clicks on each thumbnail.
images*ImageElementData[]List of images that should be rendered.
ImageComponent*ImageComponentTypeFunction that returns a React component that will be used to render images.

ImageElementData

NameTypeDescriptionDefault
url*stringImage URL.
alternateName*string Alternative text description of the image.

Design Tokens

Local tokenDefault value/Global token linked
--fs-image-gallery-widthcalc(100% + (2 * var(--fs-grid-padding)))
--fs-image-gallery-transition-timingvar(--fs-transition-timing)
--fs-image-gallery-transition-functionvar(--fs-transition-function)
--fs-image-gallery-gap-mobilevar(--fs-spacing-2)
--fs-image-gallery-gap-notebookvar(--fs-spacing-3)

Nested Elements

Controls

Local tokenDefault value/Global token linked
--fs-image-gallery-selector-control-bkg-color
var(--fs-control-bkg)
--fs-image-gallery-selector-control-border-radiusvar(--fs-border-radius-circle)
--fs-image-gallery-selector-control-shadowvar(--fs-shadow-darker)
--fs-image-gallery-selector-control-gradient-bkg-color
var(--fs-color-body-bkg)

Current Selected Image

Local tokenDefault value/Global token linked
--fs-image-gallery-current-height33.125rem
--fs-image-gallery-current-border-radiusvar(--fs-border-radius)

Selector

Local tokenDefault value/Global token linked
--fs-image-gallery-selector-max-heightvar(--fs-image-gallery-current-height)

Selector Elements

Local tokenDefault value/Global token linked
--fs-image-gallery-selector-elements-gapvar(--fs-spacing-1)
--fs-image-gallery-selector-elements-gap-notebookvar(--fs-spacing-2)
--fs-image-gallery-selector-elements-padding-mobilevar(--fs-spacing-0) var(--fs-grid-padding)
--fs-image-gallery-selector-elements-padding-notebookvar(--fs-spacing-0) 0

Selector Thumbnail

Local tokenDefault value/Global token linked
--fs-image-gallery-selector-thumbnail-width-mobile3.5rem
--fs-image-gallery-selector-thumbnail-height-mobilevar(--fs-image-gallery-selector-thumbnail-width-mobile)
--fs-image-gallery-selector-thumbnail-width-notebook4.5rem
--fs-image-gallery-selector-thumbnail-height-notebookvar(--fs-image-gallery-selector-thumbnail-width-notebook)
--fs-image-gallery-selector-thumbnail-border-radiusvar(--fs-border-radius)
--fs-image-gallery-selector-thumbnail-border-widthvar(--fs-border-width-thick)
--fs-image-gallery-selector-thumbnail-selected-border-color
var(--fs-border-color-active)
--fs-image-gallery-selector-thumbnail-selected-border-widthvar(--fs-border-width-thickest)
--fs-image-gallery-selector-thumbnail-image-border-radiusvar(--fs-border-radius-small)

Variants

With Selector (More than 1 Image)

Without Selector

Image Position

The ImagePosition prop sets the image position in the thumbnail and the gallery. You can check the first image changing its position in the examples below:

Top

Center (default)

Bottom


Customization

For further customization, you can use the following data attributes:

data-fs-image-gallery

data-fs-image-gallery="with-selector | without-selector"

data-fs-image-gallery-selector

data-fs-image-gallery-selector-control

data-fs-image-gallery-selector-control-button

data-fs-image-gallery-selector-elements

data-fs-image-gallery-selector-thumbnail