Go to rebrand

Carousel

Component responsible to create a carousel based on steps.

  • It's able to have multiple and independent carousels on the same page.
  • It's able to dispatch an event to the container element scope when a particular step is reached. This event deliveries: { currentStep, pastStep totalSteps}
  • It's able to handle the Carousel by Previous and Next buttons inside the main container or by duplicated buttons inside each step

How to use

You need import JS / CSS and use the HTML following indicated:

Import JS

<script defer src="{{ static("js/ca_styleguide_carousel.js") }}"></script>

Import CSS

<link rel="stylesheet" type="text/css" media="all" href="{{ static('css/ca_styleguide_carousel.css') }}" />

Minimal markup required

<div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper"> <div class="js-step ca-carousel__step ca-carousel__step--active" data-carousel-title="Step 1"> <button class="js-first-step">First</button> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> <button class="js-last-step">Last</button> </div> <div class="js-step ca-carousel__step" data-carousel-title="Step 2"></div> </div> </div>

The ca-carousel__step--active class is going to be applied to the visible or active step. It should only be added to the first step.

Important! If somehow you can't use data-carousel-width="auto" you should add a width to the .ca-carousel__wrapper element equal to X times the amount of steps in the carousel. Ex. for 2 steps = 200%, for 4 steps = 400%

Events

An event called com.consumeraffairs.styleguide.carousel.step is dispatched to the step container element after a new step has reached.

You can find more about UserDB tracking in the Tracking Carousel

<script> window.addEventListener('load', () => { const element = document.querySelector('.js-step-container'); element.addEventListener('com.consumeraffairs.styleguide.carousel.step', (evt) => { console.log('Event has been triggered:', evt.detail); }); }); </script>

An event called com.consumeraffairs.styleguide.carousel.stepChange is dispatched to the step container element when the carousel starts moving towards the new step.

<script> window.addEventListener('load', () => { const element = document.querySelector('.js-step-container'); element.addEventListener('com.consumeraffairs.styleguide.carousel.stepChange', (evt) => { console.log('Event has been triggered on step change:', evt.detail); }); }); </script>

Tracking Carousel

You can send Carousel information to UserDB through the following attributes:

Property Description Options
data-uapi-carousel-name Defines the name of element. submit | view | match | no_match
data-uapi-carousel Defines the carousel information '{"element": "carousel_name", "type": "carousel | multi_step", "context": { "template": "template_name", "config": "config_name", "step": 1 | 2 | 3 | 4 }}'


The carousel-form-handler.es6 adds some aditional information into the payload.context according to the STEP_EVENT:
  • "answers": Object containing all form fields wrapped by current step
  • "step_name": Value settled in data-carousel-title corresponding to the pastStep


Progress Bar

To insert a progress bar, just follow the markup structure bellow. You can use the progress bar outside from the .ca-carousel

<ul data-carousel-progress="ID_OF_CAROUSEL"> <li class="carousel-progress--current">Step 1</li> <li>Step 2</li> <li>Step 3</li> </ul>

The Carousel and Progress Bar are tied through the ID, so is mandatory to define one for your Carousel and use it as data-carousel-progress on progress bar.

  • Step 1
  • Step 2
  • Step 3

SmoothScroller Options

It's possible to configure params of SmoothScroller in case of use it. With this mechanism is possible to force the screen to scroll(up/down) to the carousel element.

In order to use it, you have to make sure the smooth scroller script is included on the page and add a data-scroll-options attribute to the .js-step-container element with the configuration object:

<script defer src="{{ static("js/ca_styleguide_smooth_scroller.js") }}"></script> <div class="js-step-container ca-carousel__wrapper" data-scroll-options='{ "duration": 1000, "offset": -80, }'>

For further reference about the configuration you can check the Smooth Scroller documentation

Height: Auto-size

If every step has very different heights you might want to use the auto-resize functionality to change the carousel height based on the current step height. To do so, you have to add a data-carousel-resize="true" attribute to the step container element:

<div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper" data-carousel-resize="true"> <div class="js-step ca-carousel__step ca-carousel__step--active"> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> <div class="js-step ca-carousel__step"></div> </div> </div>

Width: Auto-size

If you need to set the carousel width based on the total of steps. To do so, you have to add a data-carousel-width="auto" attribute to the step container element:

<div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper" data-carousel-width="auto"> <div class="js-step ca-carousel__step ca-carousel__step--active"> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> <div class="js-step ca-carousel__step"></div> </div> </div>

Loop

For infinite loop sliding set the data attribute data-carousel-loop="true" on js-step-container element.

<div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper" data-carousel-loop="true"> <div class="js-step ca-carousel__step ca-carousel__step--active"> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> <div class="js-step ca-carousel__step"></div> </div> </div>

Autoplay

For autoplay, set the data attribute data-carousel-autoplay on js-step-container element with the value in miliseconds. The default interval is 3000 miliseconds.

<div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper" data-carousel-autoplay="4000" data-carousel-loop="true" > <div class="js-step ca-carousel__step ca-carousel__step--active"> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> <div class="js-step ca-carousel__step"></div> </div> </div>

Public methods

You can access the Carousel instance on the js-step-container element in order to use the public methods available:

const element = document.querySelector('.js-step-container'); element.carousel; // Carousel instance

next()

Moves the carousel to the next step. It does nothing if the carousel is already on the last step.

const element = document.querySelector('.js-step-container'); element.carousel.next();

getTotalSteps()

Provide a number according to the total steps starting from 1.

const element = document.querySelector('.js-step-container'); element.carousel.getTotalSteps();

getCurrentStep()

Provide a number according to the current step starting from 0.

const element = document.querySelector('.js-step-container'); element.carousel.getCurrentStep();

prev()

Moves the carousel to the previous step. It does nothing if the carousel is on the first step.

const element = document.querySelector('.js-step-container'); element.carousel.prev();

moveToFirst()

Moves the carousel to the first step. It does nothing if the carousel is on the first step.

const element = document.querySelector('.js-step-container'); element.carousel.moveToFirst();

moveToLast()

Moves the carousel to the last step. It does nothing if the carousel is already on the last step.

const element = document.querySelector('.js-step-container'); element.carousel.moveToLast();

moveTo(Number)

Moves the carousel to the index step given as a parameter. It does nothing if the index number is invalid or out of range.

const element = document.querySelector('.js-step-container'); element.carousel.moveTo(2);

resize()

When the auto-resize functionality is active the steps height are being calculated only at initialization. If you need to trigger the resize event manually, you can use the resize method.

const element = document.querySelector('.js-step-container'); element.carousel.resize();


    Nested Carousels

    If you need to add a carousel inside another carousel, you need set an id to the carousel, data-carousel-nested attribute on the step container to enable the nested feature for the parent carousel and also use the carousel id as suffix on the carousel js classes:

    Let's say that the carousel id is nested, then js-step would be js-step-nested and js-next-step would be js-next-step-nested.

    Example

    <div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper" id="nested" data-carousel-nested="true"> <div class="js-step-nested ca-carousel__step ca-carousel__step--active"> <div id="step-1"> <p class="ca-h2">Main Carousel Title - Step 1</p> <div class="ca-carousel"> <div class="js-step-container ca-carousel__wrapper"> <div class="js-step ca-carousel__step ca-carousel__step--active"> <div id="step-1"> <p class="ca-h2">Nested Carousel - Step 1</p> <p>Description and content of STEP 1</p> <button class="js-next-step">Next</button> <button class="js-last-step">Last</button> </div> </div> <div class="js-step ca-carousel__step"> <div id="step-2"> <p class="ca-h2">Nested Carousel - Step 2</p> <p>Description and content of STEP 2</p> <button class="js-first-step>First</button> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> <button class="js-last-step">Last</button> </div> </div> <div class="js-step ca-carousel__step"> <div id="step-3"> <p class="ca-h2">Nested Carousel - Step 3</p> <p>Description and content of STEP 3</p> <button class="js-first-step">First</button> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> </div> </div> </div> <button class="js-next-step-nested">Next</button> <button class="js-last-step-nested">Last</button> </div> </div> <div class="js-step-nested ca-carousel__step"> <div id="step-2"> <p class="ca-h2">Main Carousel Title - Step 2</p> <p>Description and content of STEP 2</p> <button class="js-first-ste-nested">First</button> <button class="js-prev-step-nested">Previous</button> <button class="js-next-step-nested">Next</button> <button class="js-last-step-nested">Last</button> </div> </div> <div class="js-step-nested ca-carousel__step"> <div id="step-3"> <p class="ca-h2">Main Carousel Title - Step 3</p> <p>Description and content of STEP 3</p> <button class="js-first-step-nested">First</button> <button class="js-prev-step-nested">Previous</button> <button class="js-next-step-nested">Next</button> </div> </div> </div> </div>

    Demo



    Multiple steps Carousel

    You can change the amount of steps using CSS and you won't have empty spaces. To enable this feature is needed to add the js-carousel class in the carousel container. It's possible to check it in the following example:

    <div class="ca-carousel js-carousel"> <div class="js-step-container ca-carousel__wrapper" data-carousel-loop="true" > <div class="js-step ca-carousel__step ca-carousel__step--active"> <button class="js-prev-step">Previous</button> <button class="js-next-step">Next</button> </div> <div class="js-step ca-carousel__step"></div> </div> </div>

    Loop


    Progress Bar

    • Step 1
    • Step 2
    • Step 3
    • Step 4

    Height: Auto-size