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

Carousel

Slides through multiple elements using custom controls.

Import

Import the component from @faststore/ui

import { Carousel } from '@faststore/ui'

Import Styles

import '@faststore/ui/src/components/molecules/Carousel/styles.scss'

Usage

⚠️

This component is a work in progress, and in some cases, it may not perform as expected.

Default

Infinite Scroll Mode

⚠️

This mode is only supported given the following props setup: itemsPerPage={1}, variant="slide" and infiniteMode={true}

Props

NameTypeDescriptionDefault
idstringID of the current instance of the component.fs-carousel
testIdstringID to find this component in testing tools (e.g.: cypress, testing library, and jest).fs-carousel
classNamestringReturns the value of element's class content attribute.
aria-labelstringDefines a string value that labels the current element when title is not used.
infiniteModefalse | trueWhether or not the Carousel is infinite slide/scroll. Only for the `slide` variant.false
controls"complete" | "navigationArrows" | "paginationBullets"Specifies which navigation elements should be visible.complete
transition{ duration: number; property: string; delay?: number; timing?: string; }Specifies the slide transition. Only for the `slide` variant{ duration: 400, property: 'transform', }
itemsPerPagenumberSpecifies the number of items per page.1
variant"slide" | "scroll"Specifies the Carousel track variant.scroll
navigationIcons{ left?: ReactNode; right?: ReactNode; }Specifies the navigation icons.undefined

Design Tokens

Nested Elements

Track

Local tokenDefault value/Global token linked
--fs-carousel-padding-mobilevar(--fs-spacing-0) var(--fs-grid-padding)
Local tokenDefault value/Global token linked
--fs-carousel-padding-desktopvar(--fs-spacing-0) calc((100% - var(--fs-grid-max-width))/2) var(--fs-spacing-0)

Item

Local tokenDefault value/Global token linked
--fs-carousel-item-margin-rightvar(--fs-spacing-3)

Controls

Local tokenDefault value/Global token linked
--fs-carousel-controls-width3.125rem
--fs-carousel-controls-heightvar(--fs-carousel-controls-width)
--fs-carousel-controls-bkg-color
var(--fs-color-neutral-0)
--fs-carousel-controls-border-radiusvar(--fs-border-radius-circle)
--fs-carousel-controls-box-shadowvar(--fs-shadow-darker)
--fs-carousel-controls-control-leftvar(--fs-spacing-4)
--fs-carousel-controls-control-rightvar(--fs-carousel-controls-control-left)
--fs-carousel-controls-control-max-leftcalc(-1 * var(--fs-spacing-11))
--fs-carousel-controls-control-max-leftvar(--fs-carousel-controls-control-max-left)

Bullets

Local tokenDefault value/Global token linked
--fs-carousel-bullets-padding-topvar(--fs-carousel-controls-control-left)
--fs-carousel-bullets-padding-leftvar(--fs-spacing-3)
--fs-carousel-bullets-padding-rightvar(--fs-carousel-bullets-padding-left)
--fs-carousel-bullets-column-gap-mobilevar(--fs-carousel-item-margin-right)
--fs-carousel-bullets-column-gap-tabletvar(--fs-spacing-3)
--fs-carousel-bullet-width-mobile100%
--fs-carousel-bullet-width-desktopvar(--fs-spacing-1)
--fs-carousel-bullet-height-mobilevar(--fs-carousel-item-margin-right)
--fs-carousel-bullet-height-desktopvar(--fs-carousel-bullet-width-desktop)
--fs-carousel-bullet-bkg-color
var(--fs-color-neutral-3)
--fs-carousel-bullet-bkg-color-selected
var(--fs-color-main-4)
--fs-carousel-bullet-border-radiusvar(--fs-carousel-controls-border-radius)

Customization

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

data-fs-carousel

data-fs-carousel-track-container

data-fs-carousel-track

data-fs-carousel-item

data-fs-carousel-controls

data-fs-carousel-control

data-fs-carousel-bullets

data-fs-carousel-bullet

Use Cases

Using ProductCard component

For the mobile preview, please refresh the browser after resizing it.

⚠️

Considering the component structure placed inside the Carousel, determine the ideal itemsPerPage number to accommodate the items and achieve the desired UI properly.

Best Practices

✅ Do's

  • We recommend using Carousel when the total of items being displayed is at least 10 items.
  • Choose an itemsPerPage value that effectively accommodates the items within the slide without compromising the UI. Consider proposing different values for mobile and desktop.
  • Maintain the visibility of the controls (navigationArrows & paginationBullets) to ensure that users can easily navigate through the slider. On desktop, these controls are displayed on hover, allowing for intuitive item selection.

❌ Don'ts

  • Don't exaggerate the number of items according to the item's width. You can combine it, providing an alternate navigation path like a See More button to a collection. Also, make sure to check how they look in different screens.

Related components

Buy ButtonCart Item