Documentation
Feedback
Guides
Storefront Development

Storefront Development
FastStoreUI componentsMolecules
Carousel

Slides through multiple elements using custom controls.

The Carousel component slides through multiple elements using custom controls.

Import

Import the component from @faststore/ui

_10
import { Carousel } 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:

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

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

Usage

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

Default

Example
Code
itemsPerPage = 1
Example
Code
itemsPerPage = 5
Example
Code
itemsPerPage = 10

Infinite Scroll Mode

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

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.
Example
Code
itemsPerPage = 3
Example
Code
itemsPerPage = 8
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 on different screens.

Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
On this page