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.

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.

Add the styles builder to your manifest.json:

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

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

vtex-apps/carousel