Draggable & Touch-friendly Carousel In Vanilla JavaScript – embla-carousel

Preview:

Description:

The embla-carousel JavaScript library which helps developers to create a responsive, customizable, mobile-friendly carousel component on the web app.

Fully responsive based on CSS flexbox.

How to use it:

Install & download.

# Yarn
$ yarn add embla-carousel

# NPM
$ npm install embla-carousel --save

Import the embla-carousel.

import EmblaCarousel from 'embla-carousel'

Or load the compiled JavaScript in the document.

<script src="https://unpkg.com/embla-carousel"></script>

Add slides to the embla carousel.

<div class="embla" id="embla">
  <div class="embla__container">
    <div class="embla__slide">
      Slide 1
    </div>
    <div class="embla__slide">
      Slide 2
    </div>
    <div class="embla__slide">
      Slide 3
    </div>
  </div>
</div>

Initialize the embla carousel.

const embla = EmblaCarousel(document.getElementById('embla'))

The basic CSS styles for the embla carousel.

.embla {
  overflow: hidden;
}

.embla__container {
  display: flex;
  will-change: transform;
}

.embla__slide {
  position: relative;
  flex: 0 0 auto;
  width: 100%;
}

Declare different options for different breakpoints.

.embla:before {
  display: none;
  content: '{
    "slidesToScroll": 1,
    "draggable": true
  }';
}
@media (min-width: 768px) {
  .embla:before {
    content: '{
      "slidesToScroll": 2,
      "draggable": false
    }';
  }
}

Available options to customize the embla carousel.

const embla = EmblaCarousel(document.getElementById('embla'),{

      // or start, center,end, number
      align: 'center',

      // or 'y'
      axis: 'x',

      // parent container
      containerSelector: '*',

      // choose between keeping redundant snap points or trimming them
      // 'trimSnaps' or 'keepSnaps'
      containScroll: '',

      // the number of slides to show per page
      slidesToScroll: 1,

      // contains slides to the carousel viewport to prevent excessive scrolling at the beginning or the end
      containScroll: false,

      // enable draggable
      draggable: true,
      dragFree: false,

      // auto spacing
      autoSpacing: false,

      // auto resize
      autoResize: false,

      // infinite loop
      loop: false,

      // animation speed
      speed: 10,

      // start index
      // 0 = slide 1
      startIndex: 0,

      // default CSS classes
      selectedClass: 'is-selected',
      draggableClass: 'is-draggable',
      draggingClass: 'is-dragging',

      // or using dir="rtl" on the top container
      direction: 'rtl'

})

Available API methods that can be used for creating your own carousel controls.

// gets the container node
embla.containerNode()

// returns an array of slide nodes
embla.slideNodes()

// gets the current slide
embla.selectedScrollSnap()

// returns an array of numbers representing the scroll progress for each snap point
embla.scrollSnapList()

// gets the previous slide
embla.previousScrollSnap()

// checks if has previous slide
embla.canScrollPrevious()

// checks if has next slide
embla.canScrollNext()

// goes to the next slide with or without scroll snap
embla.scrollNext(snap)

// goes to the previous slide with or without scroll snap
embla.scrollPrevious(snap)

// goes to a specific slide with or without scroll snap
embla.scrollTo(index: number, snap);

// updates options
embla.reInit(options: options);

// gets the current scroll progress
embla.scrollProgress();

// mimics how CSS scroll snap behaves on mobile
// returns true or false
embla.clickAllowed();

// destroys the instance
embla.destroy()

Event handlers.

// embla.on(event, callback)
// embla.off(event, callback)

embla.on('init', function(e){
  // on init
})

embla.on('destroy', function(e){
  // on destroy
})

embla.on('select', function(e){
  // on a slide selected
})

embla.on('pointerDown', function(e){
  // on dragStart
})

embla.on('pointerUp', function(e){
  // on dragEnd
})

embla.on('click', function(e){
  // on click
})

embla.on('scroll', function(e){
  // on scroll
})

embla.on('settle', function(e){
  // allows users to hook onto when the carousel has stopped scrolling
})

Changelog:

v4.5.3 (05/24/2021)

• Fixes the broken type declarations for the useEmblaCarousel hook that was introduced in v4.5.2

v4.5.2 (05/23/2021)

• Update

v4.5.1 (04/28/2021)

• Improvements

v4.5.0 (04/22/2021)

• With this release, it’s possible to turn off the behavior where the carousel skips scroll snaps when it’s dragged vigorously. This will be an opt-in option for now, but with the next major release (v.5), this will be the default behavior.

v4.4.1 (04/21/2021)

• Update package

v4.4.0 (04/11/2021)

• With this release, it’s possible to scroll instantly to a scroll snap with the jump parameter. It’s a boolean and default is false. The following methods accept the jump parameter: scrollTo, scrollNext, and scrollPrev

v4.3.2 (04/05/2021)

• Fixed Error when scrolling between slides by dragging

v4.3.1 (04/02/2021)

• Fixed Breakpoint options not reset

v4.3.0 (03/22/2021)

• Allows you to declare different options for different breakpoints. It’s achieved by using the content attribute of the pseudo-element :before on the root node.

v4.2.1 (03/17/2021)

• Removes the transform rounding in the Translate component.

v4.2.0 (03/12/2021)

• Auto Spacing Detection
• AutoResize Option
• Root Node Method
• Bugfixes

v4.1.3 (01/06/2021)

• This release comes with a refactored eventEmitter component that slightly reduces the bundle size.

v4.1.2 (12/07/2020)

• The ScrollBounds component is now responsible for applying friction instead of the dragHandler component when the carousel is out of bounds.

v4.1.1 (11/25/2020)

• Update

v4.1.0 (11/12/2020)

• Added RTL Support

v4.0.6 (10/20/2020)

• Remove exposure of location from scrollBody and rename default named methods to base

v4.0.5 (09/30/2020)

• Check for truthy class names before toggling them

v4.0.4 (09/20/2020)

• Bugfixes

v4.0.3 (09/13/2020)

• Bugfixes

v4.0.2 (09/09/2020)

• Resize debounce bugfix

v3.0.28 (08/22/2020)

• Mark package as side effect free

v3.0.27 (08/20/2020)

• A fix for the window bind issue has been merged
• The drag handler now respects event.cancelable and bails if it returns false

v3.0.26 (08/14/2020)

• Bug fix

v3.0.25 (08/13/2020)

• Small code improvements that resulted in smaller bundle size.

v3.0.25 (08/11/2020)

• Remove unnecessary declarations

v3.0.23 (08/02/2020)

• Bugfixes

v3.0.20 (07/22/2020)

• Add Type suffix to exported types

v3.0.19 (07/20/2020)

• React dependency issue fix

v3.0.17 (07/10/2020)

• Fixed: Type definition file refers to files that don’t exist in the build

v3.0.10 (06/27/2020)

• Added React component.

v3.0.0 (06/12/2020)

• New options.
• dragStart has been renamed to pointerDown.
• dragEnd has been renamed to pointerUp.
• scrollBy() has been removed.
• scrollToProgress() has been removed.
• target : boolean for the API method scrollProgress() has been removed.
• changeOptions() has been renamed to reInit().
• scrollSnapList() now returns an array of numbers representing the scroll progress for each snap point. Indexes and slide nodes per snap point has been removed.
• Bugs fixed.

v2.9.1 (04/22/2020)

• Added scrollToProgress method

v2.9.0 (03/27/2020)

• Added a new feature which allows users to specify percentage alignment by passing a number, where a fraction like 0.2 represents 20% of the viewport size. Percentage will be measured from the start edge of the viewport.

v2.8.0 (02/26/2020)

• Added Settle event

v2.7.4 (02/13/2020)

• Fixed Android touch device event bug

v2.7.0 (01/31/2020)

• Added new scrollBy() method.

v2.6.4 (12/05/2019)

• Bugfixes

v2.6.0 (11/15/2019)

• Added clickAllowed() method.

v2.5.5 (11/09/2019)

• Package updates

v2.5.0 (10/07/2019)

• Added scrollProgress method.

v2.4.0 (08/31/2019)

• When using the option containScroll Embla will automatically merge any excessive snap points that share the same snap position

v2.3.0 (07/16/2019)

• Added ‘scroll’ event.

v2.2.0 (07/11/2019)

• Added on click API Method

v2.1.14 (07/11/2019)

• Fixed canScrollNext & canScrollPrev bug

v2.1.13 (07/10/2019)

• Updated

v2.1.10 (07/06/2019)

• New containScroll options

v2.0.3 (07/04/2019)

• Solved the Webpack 4 UMD module window issue.

v2.0.0 (06/25/2019)

• Improved drag accuracy
• Improved link handling
• More API methods added
• Changed API method names
• Removed groupedIndexes() method

v1.0.0 (06/19/2019)

• groupSlides –> slidesToScroll
• hasPreviousIndex() –> canScrollPrevious()
• hasNextIndex() –> canScrollNext()

v0.9.0 (06/16/2019)

• Added more API.

v0.8.0 (06/13/2019)

• Add: closeOnScroll option to close pickr if the user scrolls the area behind it. Useful on nested scrollable elements.
• Change: Make pickr’s position absolute to prevent sticking at the top.
• Change: Make swatches not-centered

v0.7.2 (06/08/2019)

• Drag threshold has been lowered. Less drag force is now required for a slide change to occur.