VTEX Carousel

⚠️ The Carousel app has been deprecated. Although support for this block is still granted, we strongly recommend you to update your store theme's carousel using the Slider Layout in order to keep up with the component's evolution.

The VTEX Carousel app is a store component that shows a collection of banners, and this app is used by store theme.

📢 Disclaimer: Don't fork this project; use, contribute, or open issue with your feature request.

Release schedule

Release	Status	Initial Release	Maintenance LTS Start	End-of-life	Store Compatibility
[2.x]	Current Release	2018-11-28			2.x
[1.x]	Maintenance LTS	2018-05-02	2018-11-28	March 2019	1.x

See our LTS policy for more information.

Table of Contents

• Usage
  • Blocks API
    • Configuration
  • Styles API
    • CSS namespaces
• Troubleshooting
• Contributing
• Tests

Usage

This app uses our store builder with the blocks architecture. To know more about Store Builder click here.

We add the carousel as a block in our Store.

To configure or customize this app, you need to import it in your dependencies in manifest.json.

  dependencies: {
    "vtex.carousel": "2.x"
  }

Then, add carousel block into your app theme as we do in our Store theme app.

Now, you can change the behavior of the carousel block that is in the store header. See an example of how to configure:

"carousel#home": {
    "props": {
      "autoplay": true,
      "autoplaySpeed": 4,
      "banners": [],
      "height": 440,
      "showArrows": true,
      "showDots": true
    }
  }

Blocks API

When implementing this app as a block, various inner blocks may be available. The following interface lists the available blocks within carousel and describes if they are required or optional.

"carousel": {
  "component": "Carousel"
}

For now this block does not have any required or optional blocks.

Configuration

Through the Storefront, you can change the carousel's behavior and interface. However, you also can make in your theme app, as Store theme does.

Prop name	Type	Description	Default value
autoplay	Boolean	Enable automatic banner transition	true
autoplaySpeed	Number	Set the automatic banner transition interval	5
showDots	Boolean	Shows the carousel dots	true
showArrows	Boolean	Shows the carousel arrows	true
height	Number	Set banners height	420
banners	Array(Banner)	Array of banners the will be shown in the carousel	[]

Banner:

Prop name	Type	Description	Default value
image	String	Link for the image of the banner	N/A
mobileImage	String	Link for the mobile image of the banner	N/A
tabletImage	String	Link for the table image of the banner	N/A
description	String	The image's description	N/A
url	String	The URL where the image is pointing to, in case of external route	N/A
page	String	The page where the image is pointing to	N/A
params	String	Parameters of the URL	N/A
externalRoute	Boolean	Indicates if the route is external or not	false
customInternalURL	String	The relative link to where where the image is pointing to (for internal routes)	N/A

Styles API

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the styles builder and create an app styling CSS file.

1. Add the styles builder to your manifest.json:

  "builders": {
    "styles": "1.x"
  }

2. Create a file called vtex.carousel.css inside the styles/css folder. Add your custom styles:

.container {
  margin-top: 10px;
}

CSS namespaces

Below, we describe the namespaces that are defined in the Carousel.

Class name	Description	Component Source
container	The main container of the Carousel	Carousel
sliderRoot	The main container of the Slider	Carousel
sliderFrame	The element that contains the Slides	Carousel
slide	The container of the Banner component	Carousel
arrow	The container of the arrow svg (this namespace is applied to both arrows)	Carousel
arrowLeft	The container of the left arrow svg	Carousel
arrowRight	The container of the right arrow svg	Carousel
arrowsContainerWrapper	The wrapper of the container of the arrows	Carousel
arrowsContainer	The container of the arrows	Carousel
containerDots	The main container of the dots	Carousel
notActiveDot	The element of the dots that are not actives	Carousel
dot	The element of the dot	Carousel
activeDot	The current active dot	Carousel
containerImg	The container of the image	Banner
imgRegular	The wrapper of the img element used to center the image inside the container	Banner
img	The img element	Banner
bannerLink	The a element that wraps the whole Banner component	Banner

Troubleshooting

You can check if others are passing through similar issues here. Also feel free to open issues or contribute with pull requests.

Contributing

Check it out how to contribute with this project.

Tests

To execute our tests go to react/ folder and run npm test

Travis CI