⚠️ After March 18, 2024, the FastStore documentation will be migrated to the Developer Portal. For more information, access the official release note.

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 into your FastStore project

To apply the styles of this component in your FastStore project, import the following into your stylesheet:

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

Follow the instructions in the Importing FastStore UI component styles tutorial.


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.

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


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