VTEX Carousel

Description

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

ReleaseStatusInitial ReleaseMaintenance LTS StartEnd-of-lifeStore Compatibility
2.xCurrent Release2018-11-282.x
1.xMaintenance LTS2018-05-022018-11-28March 20191.x

See our LTS policy for more information.

Table of Contents

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 nameTypeDescriptionDefault value
autoplayBooleanEnable automatic banner transitiontrue
autoplaySpeedNumberSet the automatic banner transition interval5
showDotsBooleanShows the carousel dotstrue
showArrowsBooleanShows the carousel arrowstrue
heightNumberSet banners height420
bannersArray(Banner)Array of banners the will be shown in the carousel[]

Banner:

Prop nameTypeDescriptionDefault value
imageStringLink for the image of the bannerN/A
mobileImageStringLink for the mobile image of the bannerN/A
descriptionStringThe image's descriptionN/A
urlStringThe URL where the image is pointing to, in case of external routeN/A
pageStringThe page where the image is pointing toN/A
paramsStringParameters of the URLN/A
externalRouteBooleanIndicates if the route is external or notfalse
customInternalURLStringThe 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"
  }
  1. 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 nameDescriptionComponent Source
containerThe main container of the CarouselCarousel
sliderRootThe main container of the SliderCarousel
sliderFrameThe element that contains the SlidesCarousel
slideThe container of the Banner componentCarousel
arrowThe container of the arrow svg (this namespace is applied to both arrows)Carousel
arrowLeftThe container of the left arrow svgCarousel
arrowRightThe container of the right arrow svgCarousel
arrowsContainerWrapperThe wrapper of the container of the arrowsCarousel
arrowsContainerThe container of the arrowsCarousel
containerDotsThe main container of the dotsCarousel
notActiveDotThe element of the dots that are not activesCarousel
dotThe element of the dotCarousel
activeDotThe current active dotCarousel
containerImgThe container of the imageBanner
imgRegularThe wrapper of the img element used to center the image inside the containerBanner
imgThe img elementBanner
bannerLinkThe a element that wraps the whole Banner componentBanner

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

Build Status
Coverage Status