Documentation
Feedback
Guides
Storefront Development

Storefront Development
Carousel

The Carousel slides through multiple elements using custom controls.

Slides through multiple elements using custom controls.

Import

Import the component from @faststore/ui

_10
import { Carousel } from '@faststore/ui'

Import Styles

_10
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

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 in different screens.

    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/190932/mouse-black.jpg?v=1767729450

      Apple Magic Mouse

      Original price:$999Price:$950.04
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/190903/unsplash-monitor.jpg?v=1767729451

      4k Philips Monitor 27”

      Original price:$490Price:$420
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/190904/unsplash-smart-speaker.jpg?v=1767978734

      Echo Dot Smart Speaker

      Original price:$310Price:$280
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/190901/unsplash-headphone.jpg?v=1766352858

      Aedle VK-1 L Headphone

      Original price:$150Price:$130
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/190900/unsplash-vr-glasses.jpg?v=1765997962

      Oculus VR Headset

      Original price:$344Price:$315
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/173596/est.jpg?v=1757659088

      Apple AirPods Pro

      Original price:$249Price:$229
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/179130/sint.jpg?v=1757911413

      Anker SoundCore Liberty Air

      Original price:$643.71Price:$486.34
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/171611/eius.jpg?v=1757657196

      Fujifilm X-T1 Camera

      Original price:$495.97Price:$366.11
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/159818/debitis.jpg?v=1757639123

      SANDMARC Fisheye Lens

      Original price:$946.73Price:$636.05
    • An error occurred while trying to load the image. https://storeframework.vtexassets.com/arquivos/ids/181988/nulla.jpg?v=1757915578

      Apple AirTag

      Original price:$679.29Price:$426.14

    Product Shelf

    Displays a list of products to be used as a section on the store.

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