VTEX Developer Portal

All ContributorsAll Contributors

Slider Layout is a flexible solution for building sliders of blocks within VTEX Store Framework, such as a carousel component.

:information_source: In order to use the Slider Layout as a substitute to the Carousel app, check out the Building a Carousel through lists and Slider Layout documentation.

Configuration

  1. Add the slider-layout app to your theme's dependencies in the manifest.json file:
"dependencies": {
  "vtex.slider-layout": "0.x"
}

Now, you are able to use all blocks exported by the slider-layout app. Check out the full list below:

Block nameDescription
slider-layouthttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Builds sliders of blocks for your store through its children list blocks.
slider-layout-groupEnables you to keep a group of slider-layout blocks in sync with each other. For more on this, check out the Advanced configurations section below.
  1. Add the slider-layout block to your template. For example:
  "slider-layout#text-test": {
    "props": {
      "itemsPerPage": {
        "desktop": 1,
        "tablet": 1,
        "phone": 1
      },
      "infinite": true,
      "showNavigationArrows": "desktopOnly",
      "blockClass": "carousel"
    },
    "children": ["rich-text#1", "rich-text#2", "rich-text#3"]
  },

  "rich-text#1": {
    "props": {
      "text": "Test1"
    }
  },
  "rich-text#2": {
    "props": {
      "text": "Test2"
    }
  },
  "rich-text#3": {
    "props": {
      "text": "Test3"
    }
  },
Prop nameTypeDescriptionDefault value
labelstringaria-label attribute value to be used by the <Slider/> component when rendered. The aria-label value should explicitly tell users what the HTML element being inspected is responsible for.slider
showNavigationArrowsenumWhen navigation arrows should be rendered. Possible values are: mobileOnly, desktopOnly, always, or never.always
showPaginationDotsenumWhen pagination dots should be rendered. Possible values are: mobileOnly, desktopOnly, always, or never.always
infinitebooleanWhether the slider should be infinite (true) or not (false). When this prop is set as false, the slider will have an explicit end for users.false
usePaginationbooleanWhether the slider should use slide pages (true) or not (false). When this prop is set as false, the slider will use smooth scrolling for slide navigation instead of arrows.true
itemsPerPageobjectNumber of slider items to be shown on each type of device. For more on this, check out the itemsPerPage object section below.{ desktop: 5, tablet: 3, phone: 1 }
navigationStepnumber / enumNumber of slider items that should be displayed at a time when users click on one of the slider's arrows. It is also possible to set this prop value as page, meaning that the number of slider items to be displayed when one of the arrows is clicked on is equal to the number of slider items set per page (in the itemsPerPage prop).page
slideTransitionobjectControls the transition animation between slides based on CSS attributes. For more on this, check out the slideTransition object section below.{ speed: 400, delay: 0, timing: '' }
autoplayobjectControls the autoplay feature behavior. For more on this, check out the autoplay object section below.undefined
fullWidthbooleanWhether the slides should occupy the full page width, making the arrows appear on top of them (true) or not (false).true
arrowSizenumber / objectSlider arrows size (height and width) in pixels. This is a responsive prop, which means you can pass to it an object with different values for each breakpoint (desktop, mobile, tablet, and phone).25
centerModeenum / objectDefines the slider elements positioning on the screen. Possible values are: center (elements are centered, allowing users to see a peek of the previous and next slides), to-the-left (align elements to the left side, allowing users to see a peek of the next slide, but not the previous one), and disabled (disables the feature, rendering elements on the whole screen without taking a peek in the previous and next slides). Notice: This is a responsive prop, which means you can pass to it an object with different values for each breakpoint (desktop, mobile, tablet, and phone).disabled
centerModeSlidesGapnumberNumber of pixels between slides when centerMode is set to center or to-the-left.undefined
  • itemsPerPage object
Prop nameTypeDescriptionDefault value
desktopnumberNumber of slides to be shown on desktop devices.5
tabletnumberNumber of slides to be shown on tablet devices.3
phonenumberNumber of slides to be shown on phone devices.1
  • slideTransition object
Prop nameTypeDescriptionDefault value
speednumberTransition speed (in ms).400
delaynumberDelay between slides transition (in ms).0
timingstringTiming function.''
  • autoplay object
Prop nameTypeDescriptionDefault value
timeoutnumberTimeout (in ms) between each slide.undefined
stopOnHoverbooleanWhether the auto play should stop when users are hovering the slider (true) or not (false).undefined

Advanced configurations

The slider-layout-group block is responsible for synchronizing the slides rendered by each one of the slider-layout blocks declared in it.

The slider-layout-group therefore does not render any specific component on your store's UI. In turn, it is a logical block that only expects to receive a children block list containing the desired slider-layout blocks to be rendered. For example:

{
  "slider-layout-group#test": {
    "children": [
      "slider-layout#1",
      "slider-layout#2",
      "slider-layout#3"
    ]
  }
}

Below, you can find a practical example using three slider-layout blocks inside of a slider-layout-group. Each of those slider-layouts received three rich-text blocks as children to serve as individual slides:

slider-layout-group demoslider-layout-group demo

:warning: *All slider-layout blocks declared in the slider-layout-group must receive the same configuration, meaning the same props and values. Due to implementation rules, they are only allowed to differ in their children block list. Notice the following: declaring slider-layout blocks with different configuration will result in unexpected behavior, leading to errors whose support is not granted by the VTEX Store Framework team.*

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
paginationDot--isActive
paginationDot
paginationDotsContainer
slide--firstVisible
slide--hidden
slide--lastVisible
slide--visible
slideChildrenContainer
slide
sliderArrows
sliderLayoutContainer
sliderLeftArrow
sliderRightArrow
sliderTrackContainer
sliderTrack

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Updated about a month ago


Slider Layout


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.