Quick-Start

bulma.io Carousel/Slider component

Features

Responsive

Carousel works fine on any device: desktop, tablet or mobile an adapt number of items visible (configurable).

Customization

Many options to customize behavior. Use of sass variables to easily customize design.

Javascript

Pure JavaScript to manage user interaction.

Installation
This component requires bulma.io to work. See bulma.io documentation first to know how to include it into your project.

There are several ways to get started with Bulma-extensions. You can either:

Use npm to install and stay up to date in the future

npm install bulma-carousel

Use the GitHub repository to get the latest development version

This method requires git installed on your computer.

git clone git://github.com/Wikiki/bulma-carousel.git
Starter Template

If you want to get started right away, you can use this HTML starter template. Just copy/paste this code in a file and save it on your computer.

The best way to start with carousel is to use a simple div to encaspulate your items. All child will then be used as Carousel Item:

Integration

You are only at 3 simple steps to work with bulmaCarousel.

  • Include Stylesheet

    The first step is to include the stylesheet into your project. You can use either the minified CSS version or the Sass source to integrate it into a more global project.

    <link href="~bulma-carousel/dist/css/bulma-carousel.min.css" rel="stylesheet">

    @charset "utf-8"
    
    // Import Bulma core
    @import 'bulma.sass'
    
    // Import component
    @import "bulmaCarousel.sass"

  • Include JavaScript

    Second step is to include the JavaScript part of the component.

    <script src="~bulma-carousel/dist/js/bulma-carousel.min.js"></script>

    import bulmaCarousel from '~bulma-carousel/dist/js/bulma-carousel.min.js';

  • Initiate component

    Now all that remains is to intiate the component to all elements you want to transform into a Carousel

    The attach() method always return an array of Carousel instances (even if it targets only one element).
    Instantiation method is the same for classic & hero carousel.

    // Initialize all div with carousel class
    var carousels = bulmaCarousel.attach('.carousel', options);
    
    // Loop on each carousel initialized
    for(var i = 0; i < carousels.length; i++) {
    	// Add listener to  event
    	carousels[i].on('before:show', state => {
    		console.log(state);
    	});
    }
    
    // Access to bulmaCarousel instance of an element
    var element = document.querySelector('#my-element');
    if (element && element.bulmaCarousel) {
    	// bulmaCarousel instance is available as element.bulmaCarousel
    	element.bulmaCarousel.on('before-show', function(state) {
    		console.log(state);
    	});
    }

    // Initialize all elements with carousel class.
    const carousels = bulmaCarousel.attach('.carousel', options);
    
    // To access to bulmaCarousel instance of an element
    const element = document.querySelector('#my-element');
    if (element && element.bulmaCarousel) {
    	// bulmaCarousel instance is available as element.bulmaCarousel
    }

Options
Name Description Default value
Name Description Default value
initialSlide Initial item index 0
slidesToScroll Slide to scroll on each step 1
slidesToShow Slides to show at a time 1
navigation Display navigation buttons true
navigationKeys Enable navigation with arrow keys true
navigationSwipe Enable swipe navigation true
pagination Display pagination bullets true
loop Activate loop display mode false
infinite Activate infinite display mode false
effect Animation effect for item transition (translate|fade) translate
duration Transition animation duration (in ms) 300
timing Transiation animation type ease
autoplay Autoplay carousel false
autoplaySpeed Time between each transition when autoplay is active (ms) 3000
pauseOnHover Stop autoplay when cursor hover carousel true
breakpoints List all breakpoints for responsiveness [{ changePoint: 480, slidesToShow: 1, slidesToScroll: 1 }, { changePoint: 640, slidesToShow: 2, slidesToScroll: 2 }, { changePoint: 768, slidesToShow: 3, slidesToScroll: 3 } ]
Options can be set using input data attributes. Just convert option name to dashes.
For example if you want to init a carousel with SlidesToScroll option set to "2":
<div class="carousel" data-slides-to-scroll="2">
	<div class="item-1"></div>
	<div class="item-2"></div>
	<div class="item-3"></div>
</div>
Methods

Carousel component provides some public methods to manually work with it.

next()
Slide to next item
Parameters
none
Return values
none
previous()
Slide to previous item
Parameters
none
Return values
none
start()
Start autoplay
Parameters
none
Return values
none
stop()
Stop autoplay
Parameters
none
Return values
none
show(index, force)
Show item at "index" a
Parameters
index Integer|null Index of item to show
force Boolean Animate transition if true (default) or not if false
Return values
none
reset()
Reset Carousel to initial values
Parameters
none
Return values
none
Getters

Carousel component provides some public Getters to manually access properties.

Name Description
Name Description
id Get component instance ID
index Get active item index
length Get number of items
slides Get all items as array
slidesToScroll Get current slidesToScroll
slidesToShow Get current slidesToShow
direction Get direction (rtl or ltr)
wrapper Get Carousel wrapper
wrapperWidth Get Carousel wrapper width
container Get Carousel container
containerWidth Get Carousel container width
slideWidth Get slide with
transitioner Get transitioner

Reminder: You can easily access to bulmaCarousel instance from a DOM element using the following code:

// Access to bulmaCarousel instance of an element
var element = document.querySelector('#my-element');
if (element && element.bulmaCarousel) {
	// bulmaCarousel instance is available as element.bulmaCarousel
}
Events

Carousel component comes with Events Management API so you can easily react to its behavior.

Name Description Values
Name Description Values
before:show Triggered before showing item bulmaCarousel State object instance
show Triggered when item is displayed bulmaCarousel State object instance
after:show Triggered once item has been displayed bulmaCarousel State object instance
start Triggered when autoplay start bulmaCarousel State object instance
stop Triggered when autoplay stop bulmaCarousel State object instance

Example working with "show" event:

// Initialize all elements with carousel class.
const carousels = bulmaCarousel.attach('.carousel', options);

// To access to bulmaCarousel instance of an element
const element = document.querySelector('#my-element');
if (element && element.bulmaCarousel) {
	// bulmaCarousel instance is available as element.bulmaCarousel
	element.bulmaCarousel.on('show', function(bulmaCarouselInstance) {
		console.log(bulmaCarouselInstance.index);
	});
}