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

Name	Type	Description	Default
testId	`string`	ID 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*	`ImageComponentType`	Function that returns a React component that will be used to render images.
selectedImageIdx*	`number`	The currently active thumbnail.
setSelectedImageIdx*	`(idx: number) => void`	Event handler for clicks on each thumbnail.
imagePosition	`"top" \| "center" \| "bottom"`	The position of the thumbnail and gallery image.	`center`

Image Gallery Selector

Name	Type	Description	Default
testId	`string`	ID to find this component in testing tools (e.g.: cypress, testing-library, and jest).	`fs-image-gallery-selector`
currentImageIdx*	`number`	The currently active thumbnail.
aria-label	`string`	For accessibility purposes, define a string that labels the current element.
navigationButtonLeftAriaLabel	`string`	For accessibility purposes, define a string that labels the left navigation icon button.	`Backward slide image selector`
navigationButtonRightAriaLabel	`string`	For accessibility purposes, define a string that labels the right navigation button icon.	`Forward slide image selector`
onSelect*	`(imageIdx: number) => void`	Event handler for clicks on each thumbnail.
images*	`ImageElementData[]`	List of images that should be rendered.
ImageComponent*	`ImageComponentType`	Function that returns a React component that will be used to render images.

ImageElementData

Name	Type	Description	Default
url*	`string`	Image URL.
alternateName*	`string`	Alternative text description of the image.

Design Tokens

Local token	Default value/Global token linked
`--fs-image-gallery-width`	`calc(100% + (2 * var(--fs-grid-padding)))`

`--fs-image-gallery-transition-timing`	`var(--fs-transition-timing)`
`--fs-image-gallery-transition-function`	`var(--fs-transition-function)`

`--fs-image-gallery-gap-mobile`	`var(--fs-spacing-2)`
`--fs-image-gallery-gap-notebook`	`var(--fs-spacing-3)`

Nested Elements

Controls

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

Current Selected Image

Local token	Default value/Global token linked
`--fs-image-gallery-current-height`	`33.125rem`
`--fs-image-gallery-current-border-radius`	`var(--fs-border-radius)`

Selector

Local token	Default value/Global token linked
`--fs-image-gallery-selector-max-height`	`var(--fs-image-gallery-current-height)`

Selector Elements

Local token	Default value/Global token linked
`--fs-image-gallery-selector-elements-gap`	`var(--fs-spacing-1)`
`--fs-image-gallery-selector-elements-gap-notebook`	`var(--fs-spacing-2)`
`--fs-image-gallery-selector-elements-padding-mobile`	`var(--fs-spacing-0) var(--fs-grid-padding)`
`--fs-image-gallery-selector-elements-padding-notebook`	`var(--fs-spacing-0) 0`

Selector Thumbnail

Local token	Default value/Global token linked
`--fs-image-gallery-selector-thumbnail-width-mobile`	`3.5rem`
`--fs-image-gallery-selector-thumbnail-height-mobile`	`var(--fs-image-gallery-selector-thumbnail-width-mobile)`
`--fs-image-gallery-selector-thumbnail-width-notebook`	`4.5rem`
`--fs-image-gallery-selector-thumbnail-height-notebook`	`var(--fs-image-gallery-selector-thumbnail-width-notebook)`

`--fs-image-gallery-selector-thumbnail-border-radius`	`var(--fs-border-radius)`
`--fs-image-gallery-selector-thumbnail-border-width`	`var(--fs-border-width-thick)`

`--fs-image-gallery-selector-thumbnail-selected-border-color`	`var(--fs-border-color-active)`
`--fs-image-gallery-selector-thumbnail-selected-border-width`	`var(--fs-border-width-thickest)`

`--fs-image-gallery-selector-thumbnail-image-border-radius`	`var(--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

Hero Navbar