CarouselGrid

Overview

A simplified carousel controller that uses grid-based sass calculations—along with minimal javascript—making it fully responsive and easy to implement.

Benefits

• Ultra-tiny file size (~5k minified / ~2k minified + gzipped).
• Fully responsive using grid sass calculations for primary layout (renders immediately instead of waiting for javascript manipulations).
• Multiple intuitive ways to control with arrows, dots, mouse grabs, mouse slides, or finger slides—however a user wants to interact!

Installing Instructions

# NPM
npm install carousel-grid

# CDN
https://unpkg.com/carousel-grid@latest/carousel-grid.js

# Include in your project js file
import CarouselGrid from 'carousel-grid';

# Declare globally, pass context, then initialize
global.carouselGrid = new CarouselGrid(this.context);
global.carouselGrid.init();

💡 Note: There is a helper script located in the base.html file at the bottom that watches carousels in PageBuilder and re-initializes them automatically when content is changed by the user, found here /assets/scripts/pb-helper.js.

Key Elements

In this basic example below, there are a few key elements to consider to get CarouselGrid working as expected.

1. The [data-carousel-grid] data attribute is the selector that initializes the javascript logic, it needs to be included in the div that wraps the main carousel.
2. The .carousel-grid class applies the grid-based sass styling calculations and should be in the div that wraps the main carousel.
3. The .arrows-pos-side class selects the arrow style/position to be used, and can be changed or customized in the arrows css file.
4. The .slider class is the selector used to apply javascript controls to the containing slides.
5. The .slide class should wrap each slide element in the carousel.
6. The .controls-container is where the arrow controls live. The .dots div is where the dot controls live. Both arrows and dots can be shown or hidden globally by editing the .carousel-grid css, or individually to the carousel by targeting the .carousel-example-1 css.

💡 Tip: Apply global styling in the .carousel-grid class for arrows and dots so the user experience is consistent across the entire website, as opposed to setting specific styles for each carousel.

Basic Example

<section id="carousel-example-1">
    <div class="carousel-grid arrows-pos-side" data-carousel-grid>
    <h3>Example Carousel</h3>
    <div class="controls-container">
        <div>
            <button class="scroll-arrow scroll-left icon-arrow-left" aria-label="Scroll carousel left"></button>
            <button class="scroll-arrow scroll-right icon-arrow-right" aria-label="Scroll carousel right"></button>
        </div>
    </div>
    <div class="slider"
        tabindex=0
        data-mobile-slides="1"
        data-tablet-slides="1"
        data-desktop-slides="1"
        data-center-arrow=".slide">                
            <div class="slide">Slide #1</div>
            <div class="slide">Slide #2</div>
            <div class="slide">Slide #3</div>
            <div class="slide">Slide #4</div>
            <div class="slide">Slide #5</div>
            <div class="slide">Slide #6</div> 
    </div>
    <div class="dots"></div>
</div>
</section>

Settings

You can define data attributes to the container that wraps the slides

Option	Type	Default	Description
tab-index	int	0	Uses to give keyboard focus to the main slider container, for accessibility.
data-mobile-slides	float	1	Specify how many slides are show at the mobile breakpoint. You can use a decimal if you want to show fractional slides (ex: 1.4)
data-tablet-slides	float	1	Specify how many slides are show at the tablet breakpoint. You can use a decimal if you want to show fractional slides.
data-desktop-slides	float	1	Specify how many slides are show at the desktop breakpoint. You can use a decimal if you want to show fractional slides.
data-center-arrow	classname or selector	img	The arrows that control the carousel can be centered on any element found in a slide, can you can target a classname or an html element with a selector (ex: img, .classname, etc...)
data-auto-scroll-speed	time (in ms)	0	Will auto-scroll the carousel in an interval set in milliseconds (ex: 4000 = scrolls every 4 seconds). Clicking on carousel controls disables auto scroll functionality. Auto Scroll is disabled after 60 seconds as to not get annoying.
data-start-at	int	0	Will side to the specified slide number when initialized.

Styling

Global styling and sass calculation for the grid based carousels is maintained in /assets/scss/gobal-elements/carousel/_grid.scss

Default :root variables for number of slides per breakpoint are defined at the top of the file, but can be overridden using data attributes in the carousel html, as described above in the settings section.

:root {
    --mobile-slides: 1;
    --tablet-slides: 1;
    --desktop-slides: 1;

    --mobile-gap: 1px;
    --tablet-gap: 1px;
    --desktop-gap: 1px;
}

.global-card-gaps {
    --mobile-gap: #{$card-col-spacing-Sm}px;
    --tablet-gap: #{$card-col-spacing-Md}px;
    --desktop-gap: #{$card-col-spacing-Lg}px;
}

💡 Tip: If you want to apply consistent gaps for your carousel card elements, simply add the .global-card-gaps class to the div that wraps the main carousel. This will uses the global card spacing variables for consistent gap spacing that matches other grid elements and their breakpoints on the site.

The default :root variables for the gap between slides per breakpoint can be overridden by targeting specific carousel via sass like this:

#carousel-example-1 {
    .slider {
        --mobile-gap: 1px;
        --tablet-gap: 1px;
        --desktop-gap: 1px;
    }
}

Misc Developer Notes

• There is logic built into the library that prevents multiple eventListeners if the carousel is re-initialized. This is helpful for systems that add or remove carousel content in real-time, and need to re-initialize the carousel to work with the newly added content.
• Includes logic for an image gallery that highlights the corresponding thumbnail to the active image gallery slide.
• Currently this library was created to be very specific to the BigCommerce framework, but could be modified to be more general for other frameworks to use.

Dependencies

jQuery -- while I tried to use completely vanilla javascript, there were some slide animations that were easily rendered using jQuery that simplified things.